feat: document @valuepool

Author: oetr

docs/mutation-framework.md

@@ -317,6 +317,163 @@ class SimpleClassFuzzTests {
 }
 ```
 
+## @ValuePool: Guide fuzzing with custom values
+
+The `@ValuePool` annotation lets you provide concrete example values that Jazzer's mutators will use when generating test inputs.
+This helps guide fuzzing toward realistic or edge-case values relevant to your application.
+
+### Basic Usage
+
+You can apply `@ValuePool` in two places:
+- **On method parameters** - values apply only to that parameter's type
+- **On the test method itself** - values propagate to all matching types across all parameters
+
+**Example:**
+```java
+@FuzzTest
+void fuzzTest(@ValuePool(value = {"mySupplier"}) Map foo) {
+    // Strings from mySupplier feed the Map's String mutator
+    // Integers from mySupplier feed the Map's Integer mutator
+}
+
+@FuzzTest
+@ValuePool(value = {"mySupplier"})
+void anotherFuzzTest(Map foo, String bar) {
+    // Values propagate to ALL matching types:
+    // - String mutator for Map keys in 'foo'
+    // - String mutator for 'bar' 
+    // - Integer mutator for Map values in 'foo'
+}
+
+static Stream mySupplier() {
+    return Stream.of("example1", "example2", "example3", 1232187321, -182371);
+}
+```
+
+### How Type Matching Works
+
+Jazzer automatically routes values to mutators based on type:
+- Strings in your value pool → String mutators
+- Integers in your value pool → Integer mutators
+- Byte arrays in your value pool → byte[] mutators
+
+**Type propagation happens recursively by default**, so a `@ValuePool` on a `Map<String, Integer>` will feed both the String mutator (for keys) and Integer mutator (for values).
+
+---
+
+### Supplying Values: Two Mechanisms
+
+#### 1. Supplier Methods (`value` field)
+
+Provide the names of static methods that return `Stream<?>`:
+```java
+@ValuePool(value = {"mySupplier", "anotherSupplier"})
+```
+
+**Requirements:**
+- Methods must be `static`
+- Must return `Stream<?>` 
+- Can contain mixed types (Jazzer routes by type automatically)
+
+#### 2. File Patterns (`files` field)
+
+Load files as `byte[]` arrays using glob patterns:
+```java
+@ValuePool(files = {"*.jpeg"})              // All JPEGs in working dir
+@ValuePool(files = {"**.xml"})              // All XMLs recursively
+@ValuePool(files = {"/absolute/path/**"})   // All files from absolute path
+@ValuePool(files = {"*.jpg", "**.png"})     // Multiple patterns
+```
+
+**Glob syntax:** Follows `java.nio.file.PathMatcher` with `glob:` pattern rules.
+
+**You can combine both mechanisms:**
+```java
+@ValuePool(value = {"mySupplier"}, files = {"test-data/*.json"})
+```
+
+---
+
+### Configuration Options
+
+#### Mutation Probability (`p` field)
+Controls how often values from the pool are used versus randomly generated values.
+```java
+@ValuePool(value = {"mySupplier"}, p = 0.3)  // Use pool values 30% of the time
+```
+
+**Default:** `p = 0.1` (10% of mutations use pool values)
+**Range:** 0.0 to 1.0
+
+#### Type Propagation (`constraint` field)
+
+Controls whether the annotation affects nested types:
+```java
+// Default: RECURSIVE - applies to all nested types
+@ValuePool(value = {"mySupplier"}, constraint = Constraint.RECURSIVE)
+
+// DECLARATION - applies only to the annotated type, not subtypes
+@ValuePool(value = {"mySupplier"}, constraint = Constraint.DECLARATION)
+```
+
+**Example of the difference:**
+```java
+// With RECURSIVE (default):
+@ValuePool(value = {"stringSupplier"}) Map> data
+// Strings feed both Map keys AND List elements
+
+// With DECLARATION:
+@ValuePool(value = {"stringSupplier"}, constraint = DECLARATION) Map> data
+// Strings only feed Map keys, NOT List elements
+```
+
+---
+
+### Complete Example
+```java
+class MyFuzzTest {
+    static Stream edgeCases() {
+        return Stream.of(
+            "", "null", "alert('xss')",  // Strings
+            0, -1, Integer.MAX_VALUE,    // Integers
+            new byte[]{0x00, 0xFF}       // A byte array
+        );
+    }
+    
+    @FuzzTest
+    @ValuePool(
+        value = {"edgeCases"},
+        files = {"test-inputs/*.bin"},
+        p = 0.25  // Use pool values 25% of the time
+    )
+    void testParser(String input, Map config, byte[] data) {
+        // All three parameters get values from the pool:
+        // - 'input' gets Strings
+        // - 'config' keys get Strings, values get Integers
+        // - 'data' gets bytes from both edgeCases() and *.bin files
+    }
+}
+```
+
+---
+
+#### Max Mutations (`maxMutations` field)
+
+After selecting a value from the pool, the mutator can apply additional random mutations to it.
+```java
+@ValuePool(value = {"mySupplier"}, maxMutations = 5)
+```
+
+**Default:** `maxMutations = 1` (one additional mutation applied)
+**Range:** 0 or higher
+
+**How it works:** If `maxMutations = 5`, Jazzer will:
+1. Select a value from your pool (e.g., `"example"`)
+2. Apply up to 5 random mutations (e.g., `"example"` → `"exAmple"` → `"exAmple123"` → ...)
+
+This helps explore variations of your seed values while staying close to realistic inputs.
+
+
 ## FuzzedDataProvider
 
 The `FuzzedDataProvider` is an alternative approach commonly used in programming