docs(cache): document cache persistence behavior per runner

Add a "Cache Persistence by Runner" section explaining that cache write
behavior differs by runner: Docker and Bubblewrap use read-write bind
mounts (writes persist), while QEMU uses read-only 9p with overlay by
default (writes discarded). Update virtiofs section to clarify it enables
cache persistence for QEMU.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: toabctl

docs/BUILD-CACHE.md

@@ -11,9 +11,9 @@ As each build often requires all the same packages, it can be very inefficient t
 
 ## How to use it
 
-When you run `melange build`, you can specify a cache directory with the `--cache-dir` flag. The value you provide here should be a path to a directory on your local filesystem. This local directory will be mounted into the build workspace (e.g. a running container) at the path `/var/cache/melange` as a read/write volume.
+When you run `melange build`, you can specify a cache directory with the `--cache-dir` flag. The value you provide here should be a path to a directory on your local filesystem. This local directory will be mounted into the build workspace (e.g. a running container) at the path `/var/cache/melange`.
 
-This enables you to speed up builds by preloading data into the cache before you run `melange build`. You can additionally use this mounted directory to persist cache data generated by the build itself, taking advantage of the cache in subsequent builds.
+This enables you to speed up builds by preloading data into the cache before you run `melange build`. Depending on the runner you use, you may also be able to persist cache data generated by the build itself for use in subsequent builds (see [Cache Persistence by Runner](#cache-persistence-by-runner) below).
 
 ### Example: Go Modules
 
@@ -45,7 +45,7 @@ pipeline:
 
 Now you're all set! If you've already downloaded the Go modules you need for your Go project to your local filesystem, you'll no longer need to wait for Melange to download those Go modules during every build. This can significantly speed up builds!
 
-Keep in mind that because the build cache is a read/write-able mount, modifications to data in this directory during a Melange build **will affect** your local filesystem.
+**Note:** Whether modifications to the cache during a build persist to your local filesystem depends on which runner you use. See [Cache Persistence by Runner](#cache-persistence-by-runner) for details.
 
 ### Example: Python UV
 
@@ -123,4 +123,62 @@ pipeline:
       pip install -r requirements.txt
 ```
 
-This caching support helps significantly speed up Python builds by avoiding repeated downloads of packages across builds.
+This caching support helps significantly speed up Python builds by avoiding repeated downloads of packages across builds.
+
+### Example: Maven Dependencies
+
+Maven caching is automatically enabled when using the `maven/configure-mirror` or `maven/pombump` pipelines. When a cache directory is mounted at `/var/cache/melange`, the pipelines automatically configure Maven to use `/var/cache/melange/m2repository` as the local repository.
+
+To use Maven caching, simply provide a cache directory:
+
+```shell
+melange build --cache-dir /path/to/my/cache ...
+```
+
+No additional configuration is required in your Melange config. The Maven pipelines detect the mounted cache directory and configure the local repository path automatically. This is useful for Java projects with many dependencies (e.g., apicurio-registry requires over 1 GB of dependencies).
+
+On subsequent builds, Maven will reuse the downloaded dependencies from the cache, avoiding redundant downloads.
+
+## Cache Persistence by Runner
+
+The cache directory mount behavior varies depending on which runner you use:
+
+| Runner | Mount Type | Writes Persist to Host |
+|--------|------------|------------------------|
+| Docker | Bind mount (read-write) | Yes |
+| Bubblewrap | Bind mount (read-write) | Yes |
+| QEMU (default) | 9p (read-only) + overlay | No |
+| QEMU (virtiofs) | virtiofs (read-write) | Yes |
+
+### Docker and Bubblewrap
+
+Both Docker and Bubblewrap mount the cache directory as a standard read-write bind mount. Any modifications made to `/var/cache/melange` during the build **will directly affect** your local filesystem. This allows builds to populate the cache for use in subsequent builds.
+
+### QEMU (default, without virtiofs)
+
+By default, QEMU mounts the cache directory using the 9p protocol with a read-only flag. To allow builds to write to the cache, an overlay filesystem is layered on top:
+
+- **Lower layer:** Read-only 9p mount of your host cache directory
+- **Upper layer:** Temporary writable directory inside the guest
+
+This means builds can read from your pre-populated cache, but any writes during the build go to the overlay's upper directory and **are discarded** when the build completes. To persist cache writes with QEMU, enable virtiofs (see below).
+
+## QEMU Runner: virtiofs for Cache Directory
+
+When using the QEMU runner, the default 9p mount does not persist cache writes to the host. To enable cache persistence (and improve I/O performance), you can use virtiofs instead.
+
+To enable virtiofs for the cache directory, set the `QEMU_USE_VIRTIOFS` environment variable:
+
+```shell
+QEMU_USE_VIRTIOFS=1 melange build --runner qemu --cache-dir /path/to/cache ...
+```
+
+**Requirements:**
+- The `virtiofsd` binary must be available on the host system (checked at `/usr/libexec/virtiofsd`, `/usr/lib/qemu/virtiofsd`, or in `$PATH`). Alternatively, set `QEMU_VIRTIOFS_PATH` to a directory containing the `virtiofsd` binary (useful for macOS/brew or non-standard installations).
+- The host system must support virtiofs (Linux with appropriate kernel support)
+
+When virtiofs is enabled, the cache directory is mounted as a read-write virtiofs share, providing:
+- **Cache persistence:** Writes during the build are saved to your host filesystem
+- **Better I/O performance:** virtiofs offers improved performance compared to 9p
+
+If `QEMU_USE_VIRTIOFS=1` is set but `virtiofsd` is not found, melange will return an error. If the environment variable is not set or set to `0`, the default 9p+overlay mount is used and cache writes are not persisted.