@@ -11,12 +11,15 @@ if let localPath = Context.environment["SWIFT_JAVA_JNI_CORE_PATH"] {
   swiftJavaJNICoreDep = .package(url: "https://github.com/swiftlang/swift-java-jni-core", branch: "main")
 }
 
-// Set SWIFTJAVA_DOCC_PLUGIN_INSTALL=1 to install the docc-plugin automatically.
+// Set SWIFTJAVA_DOCC_PLUGIN_INSTALL=1 to install the docc-plugin automatically,
+// or DOCC_PLUGIN_PATH=<path> to point at a local checkout.
 // This is a workaround because swift-subprocess includes the plugin explicitly,
 // which breaks tools trying to add `swift package add-dependency` the plugin
 // to swift-java because it thinks the plugin was already added, but it is not.
 let extraDependencies: [Package.Dependency]
-if Context.environment["SWIFTJAVA_DOCC_PLUGIN_INSTALL"] == "1" {
+if let localPath = Context.environment["DOCC_PLUGIN_PATH"] {
+  extraDependencies = [.package(path: localPath)]
+} else if Context.environment["SWIFTJAVA_DOCC_PLUGIN_INSTALL"] == "1" {
   extraDependencies = [
     .package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.5.0")
   ]
 
@@ -160,9 +160,9 @@ public struct Configuration: Codable {
   public var singleType: String?
 
   /// If set, JExtract (JNI mode) will write a linker version script to this
-  /// path, listing all generated JNI ``@_cdecl`` entry-point symbols as
+  /// path, listing all generated JNI `@_cdecl` entry-point symbols as
   /// global exports and hiding everything else with `local: *`. Pass this
-  /// file to the linker via ``-Xlinker --version-script=<path>`` to enable
+  /// file to the linker via `-Xlinker --version-script=<path>` to enable
   /// precise dead-code elimination of unused Swift code in the final shared
   /// library.
   public var linkerExportListOutput: String?
@@ -306,14 +306,44 @@ public struct Configuration: Codable {
   }
 
   /// The Java classes that should be translated to Swift. The keys are
-  /// canonical Java class names (e.g., java.util.Vector) and the values are
-  /// the corresponding Swift names (e.g., JavaVector).
+  /// canonical Java class names (e.g., java.util.ArrayList) and the values are
+  /// the corresponding Swift names (e.g., JavaArrayList).
+  ///
+  /// Example:
+  /// ```json
+  /// {
+  ///   "classes": {
+  ///     "java.util.ArrayList": "JavaArrayList",
+  ///     "java.util.HashMap": "JavaHashMap"
+  ///   }
+  /// }
+  /// ```
   public var classes: [String: String]? = [:]
 
-  // Compile for the specified Java SE release.
+  /// Compile for the specified Java SE release.
+  ///
+  /// `JavaVersion` is an integer identifying a Java SE release, in the same
+  /// shape as `javaSourceLevel`. Supported values:
+  ///
+  /// - `17`
+  /// - `18`
+  /// - `21`
+  /// - `22`
+  /// - `24`
+  /// - `25`
   public var sourceCompatibility: JavaVersion?
 
-  // Generate class files suitable for the specified Java SE release.
+  /// Generate class files suitable for the specified Java SE release.
+  ///
+  /// `JavaVersion` is an integer identifying a Java SE release, in the same
+  /// shape as `javaSourceLevel`. Supported values:
+  ///
+  /// - `17`
+  /// - `18`
+  /// - `21`
+  /// - `22`
+  /// - `24`
+  /// - `25`
   public var targetCompatibility: JavaVersion?
 
   /// Filter input Java types by their package prefix if set
 
@@ -1,6 +1,10 @@
 # Android
 
-## R8/Proguard Rules
+Hints and patterns for using swift-java on Android.
+
+## Overview
+
+### R8/Proguard Rules
 
 Since swift-java uses JNI and reflection APIs, we must tell the R8 optimizer to ignore our wrapped types,
 otherwise we will run into runtime crashes, because types are stripped from the APK/AAR.
@@ -16,7 +20,7 @@ For example, if your library is named is `org.swift.exampleapp`, then add the fo
 -keep interface org.swift.exampleapp.** { *; }
 ```
 
-## Android Core Library Desugaring
+### Android Core Library Desugaring
 
 If you are using [Core Library Desugaring](https://developer.android.com/studio/write/java8-support) in your
 Android project, you must enable the `AndroidCoreLibraryDesugaring` trait to ensure that the SwiftJava wrappers
 
@@ -2,6 +2,12 @@
 
 Orientation guide for choosing the right swift-java tool for your interop task.
 
+## Overview
+
+swift-java has two directions of interop, each with a preferred entry point.
+Start here to figure out which tool matches your task, then follow the links
+to the per-tool documentation.
+
 ### Which mode should I use?
 
 #### Calling Swift from Java
 
@@ -2,6 +2,13 @@
 
 When using the `jextract` tool to wrap your Swift APIs as a Java library, several compiler and linker options can substantially reduce the final binary size by stripping dead code that would otherwise be retained.
 
+## Overview
+
+The compiler and linker options below trim the shipped library by stripping
+Swift symbols that JNI never calls, then dead-stripping the resulting
+unreachable code. Applied together, they can significantly reduce the final
+`.so`/`.dylib` size compared to a default release build.
+
 ### Requirements
 
 Full binary-size optimization requires **Swift 6.3 or later**. Swift 6.3 introduced the `@used` attribute, which `JExtractSwiftPlugin` attaches to every generated JNI entry point so the compiler cannot eliminate them before the linker has a chance to see them.
 
@@ -2,6 +2,13 @@
 
 SwiftJava tools can be configured using the `swift-java.config` file.
 
+## Overview
+
+The `swift-java.config` file lives alongside each target that needs
+swift-java code generation. It selects tool modes, sets output paths,
+and controls per-mode filters. Below: the file layout, then the full
+list of supported keys.
+
 ### The swift-java.config file
 
 You can refer to the `SwiftJavaConfigurationShared/Configuration` struct to learn about the supported options.
@@ -13,7 +20,7 @@ please refer to the options documentation for details on their behavior.
 
 The configuration is a JSON 5 file, which among other things allows `//` and `/* */` comments, so feel free to add line comments explaining rationale for some of the settings in your configuration.
 
-## Supported configuration options
+### Supported configuration options
 
 <!--   DO NOT EDIT TEXT INSIDE THE SWIFT_JAVA_CONFIG_DOCS BLOCK     -->
 <!--   Use the ./scripts/generate-config-docs.py to re-generate     -->
@@ -231,9 +238,9 @@ If set, only generate bindings for this single Swift type name
 - **Type:** `String?`
 
 If set, JExtract (JNI mode) will write a linker version script to this
-path, listing all generated JNI ``@_cdecl`` entry-point symbols as
+path, listing all generated JNI `@_cdecl` entry-point symbols as
 global exports and hiding everything else with `local: *`. Pass this
-file to the linker via ``-Xlinker --version-script=<path>`` to enable
+file to the linker via `-Xlinker --version-script=<path>` to enable
 precise dead-code elimination of unused Swift code in the final shared
 library.
 
@@ -413,8 +420,18 @@ The Java class path that should be passed along to the swift-java tool.
 - **Default:** empty dictionary (`[:]`)
 
 The Java classes that should be translated to Swift. The keys are
-canonical Java class names (e.g., java.util.Vector) and the values are
-the corresponding Swift names (e.g., JavaVector).
+canonical Java class names (e.g., java.util.ArrayList) and the values are
+the corresponding Swift names (e.g., JavaArrayList).
+
+Example:
+```json
+{
+  "classes": {
+    "java.util.ArrayList": "JavaArrayList",
+    "java.util.HashMap": "JavaHashMap"
+  }
+}
+```
 
 ---
 
@@ -424,6 +441,16 @@ the corresponding Swift names (e.g., JavaVector).
 
 Compile for the specified Java SE release.
 
+`JavaVersion` is an integer identifying a Java SE release, in the same
+shape as `javaSourceLevel`. Supported values:
+
+- `17`
+- `18`
+- `21`
+- `22`
+- `24`
+- `25`
+
 ---
 
 #### targetCompatibility
@@ -432,6 +459,16 @@ Compile for the specified Java SE release.
 
 Generate class files suitable for the specified Java SE release.
 
+`JavaVersion` is an integer identifying a Java SE release, in the same
+shape as `javaSourceLevel`. Supported values:
+
+- `17`
+- `18`
+- `21`
+- `22`
+- `24`
+- `25`
+
 ---
 
 #### javaFilterInclude
 
@@ -7,6 +7,6 @@ Automatic Java wrappers for existing Swift code, generated by `swift-java jextra
 
 `jextract` is the *Java source-generation* part of swift-java.
 
-## Workflow 
+### Workflow
 
 TODO: document all this
@@ -17,7 +17,7 @@ directly — see <doc:FeaturesJavaKitMacros>.
 
 For the full feature matrix, see <doc:FeaturesOverview>.
 
-## Workflow
+### Workflow
 
 The typical pipeline has three steps, though the SwiftPM plugin can drive all
 of them for you.
@@ -62,7 +62,7 @@ swift-java wrap-java \
   Sources/JavaSieve/swift-java.config
 ```
 
-## The SwiftPM plugin
+### The SwiftPM plugin
 
 Most projects do **not** invoke the CLI directly. The `SwiftJavaPlugin`
 build-tool plugin (see `Plugins/SwiftJavaPlugin/SwiftJavaPlugin.swift`)
@@ -83,7 +83,7 @@ Wire it up in your `Package.swift`:
 
 See <doc:SwiftPMPlugin> for the plugin's full contract.
 
-## `swift-java.config` schema (wrap-java fields)
+### `swift-java.config` schema (wrap-java fields)
 
 The full schema lives in
 `Sources/SwiftJavaConfigurationShared/Configuration.swift`. The fields
@@ -101,7 +101,7 @@ that matter for `wrap-java` are:
 
 The config file is JSON5, so `//` and `/* */` comments are permitted.
 
-## CLI flags
+### CLI flags
 
 `swift-java wrap-java --help` (from
 `Sources/SwiftJavaTool/Commands/WrapJavaCommand.swift`) exposes:
@@ -120,7 +120,7 @@ The config file is JSON5, so `//` and `/* */` comments are permitted.
 | `-o <path>` / `--output-directory <path>`       | (Inherited) Output directory.                                                               |
 | `-l <level>` / `--log-level <level>`            | (Inherited) `trace`, `debug`, `info`, `notice`, `warning`, `error`, `critical`.             |
 
-## Walkthrough: wrapping a JDK class
+### Walkthrough: wrapping a JDK class
 
 The simplest possible sample: wrap `java.math.BigInteger` and use it to test
 primality. See `Samples/JavaProbablyPrime/`.
@@ -134,7 +134,7 @@ primality. See `Samples/JavaProbablyPrime/`.
    }
 }
 
-## Walkthrough: wrapping an external JAR
+### Walkthrough: wrapping an external JAR
 
 `Samples/JavaSieve/` wraps a third-party Java library (a quadratic-sieve
 prime finder) plus `java.math.RoundingMode` for enum-constant access. The
@@ -149,7 +149,7 @@ config lists both the classpath and the target classes.
    }
 }
 
-## Walkthrough: Maven dependency
+### Walkthrough: Maven dependency
 
 `Samples/JavaDependencySampleApp/` wraps `org.apache.commons:commons-csv`
 straight from Maven Central. The config here can be near-empty because
@@ -164,7 +164,7 @@ straight from Maven Central. The config here can be near-empty because
    }
 }
 
-## Feature matrix
+### Feature matrix
 
 Legend: ✅ supported, ❌ not supported, 🟡 partial / work-in-progress.
 
@@ -187,7 +187,7 @@ Legend: ✅ supported, ❌ not supported, 🟡 partial / work-in-progress.
 | JAR-only workflow (`swift-java configure --jar` -> `wrap-java`)                  | ✅       |
 | SwiftPM plugin auto-invocation                                                   | ✅       |
 
-## See also
+### See also
 
 - <doc:FeaturesJavaKitMacros> — the underlying macro surface that `wrap-java` generates.
 - <doc:SwiftJavaCommandLineTool> — full reference for the `swift-java` CLI (all subcommands).