diff --git a/README.md b/README.md
index d11e1855..fa3f8394 100644
--- a/README.md
+++ b/README.md
@@ -147,6 +147,8 @@ The workflow output `cache-hit` is set to indicate if an exact match was found f
 
 The cache input is optional, and caching is turned off by default.
 
+**Maven Wrapper:** when `cache: 'maven'` is enabled, the action also caches and restores the Maven Wrapper distribution downloaded to `~/.m2/wrapper/dists` (in addition to the local repository), so wrapper-based (`./mvnw`) builds don't re-download the wrapper on every run. This is keyed on `**/.mvn/wrapper/maven-wrapper.properties` as shown above.
+
 #### Caching gradle dependencies
 ```yaml
 steps:
diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md
index 2b769abd..65193c4b 100644
--- a/docs/advanced-usage.md
+++ b/docs/advanced-usage.md
@@ -516,6 +516,8 @@ The two `settings.xml` files created from the above example look like the follow
 
 ***NOTE***: The `settings.xml` file is created in the Actions `$HOME/.m2` directory. If you have an existing `settings.xml` file at that location, it will be overwritten. See [below](#apache-maven-with-a-settings-path) for using the `settings-path` to change your `settings.xml` file location.
 
+***NOTE***: The generated `settings.xml` sets `<interactiveMode>false</interactiveMode>` so that Maven never blocks a CI run waiting on an interactive prompt. This is applied automatically whenever the action generates `settings.xml`.
+
 If you don't want to overwrite the `settings.xml` file, you can set `overwrite-settings: false`
 
 ### Extra setup for pom.xml:
@@ -601,6 +603,44 @@ jobs:
 - This setting only affects Maven. It has no effect on Gradle, sbt, or other build tools.
 - `-ntp` only controls transfer/progress output; it does not change whether Maven runs in batch mode. Use `-B`/`--batch-mode` (or `<interactiveMode>false</interactiveMode>` in `settings.xml`) if you also want non-interactive runs.
 
+## Java problem matcher (compiler annotations)
+
+`setup-java` registers a [problem matcher](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md) for Java after installing the JDK. It scans the log output of subsequent steps and turns `javac` diagnostics into GitHub [annotations](https://docs.github.com/actions/using-workflows/workflow-commands-for-github-actions#setting-a-warning-message) that appear in the run summary and inline on the affected files. It matches two kinds of lines:
+
+- Compiler errors and warnings, e.g. `App.java:12: error: cannot find symbol` (owner `javac`).
+- Uncaught-exception header lines, e.g. `Exception in thread "main" ...`; because these lines have no file or line captures, they appear as log/run-level annotations rather than inline file annotations (owner `java`).
+
+This is enabled by default and requires no configuration.
+
+### Disabling the problem matcher
+
+There is no action input to turn the matcher off, but you can disable it for the rest of the job with the built-in [`remove-matcher`](https://github.com/actions/toolkit/blob/main/docs/problem-matchers.md#remove-a-problem-matcher) workflow command. Pass the matcher **owner** (not a file name); the Java matcher defines two owners, `javac` and `java`, so remove both to fully suppress it:
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v6
+    - uses: actions/setup-java@v5
+      with:
+        distribution: '<distribution>'
+        java-version: '21'
+
+    - name: Disable the Java problem matcher
+      run: |
+        echo "::remove-matcher owner=javac::"
+        echo "::remove-matcher owner=java::"
+
+    - name: Build with Maven
+      run: mvn -B package --file pom.xml
+```
+
+***NOTES***:
+- `remove-matcher` only stops annotations from being created; the underlying compiler output is unchanged, so a failing `javac`/build still fails the step.
+- The command is scoped to the job, so add the step right after `setup-java` (and before your build) in every job where you want the matcher disabled.
+
 ## Publishing using Gradle
 ```yaml
 jobs: