add some initial java docs

docs/configuration/java.mdx

@@ -0,0 +1,153 @@
+---
+title: "Java Configuration"
+description: "Configure Codeflash for Java projects using codeflash.toml"
+icon: "java"
+sidebarTitle: "Java (codeflash.toml)"
+keywords:
+  [
+    "configuration",
+    "codeflash.toml",
+    "java",
+    "maven",
+    "gradle",
+    "junit",
+  ]
+---
+
+# Java Configuration
+
+Codeflash stores its configuration in `codeflash.toml` under the `[tool.codeflash]` section.
+
+## Full Reference
+
+```toml
+[tool.codeflash]
+# Required
+module-root = "src/main/java"
+tests-root = "src/test/java"
+language = "java"
+
+# Optional
+test-framework = "junit5"        # "junit5", "junit4", or "testng"
+disable-telemetry = false
+git-remote = "origin"
+ignore-paths = ["src/main/java/generated/"]
+```
+
+All file paths are relative to the directory containing `codeflash.toml`.
+
+<Info>
+Codeflash auto-detects most settings from your project structure. Running `codeflash init` will set up the correct config — manual configuration is usually not needed.
+</Info>
+
+## Auto-Detection
+
+When you run `codeflash init`, Codeflash inspects your project and auto-detects:
+
+| Setting | Detection logic |
+|---------|----------------|
+| `module-root` | Looks for `src/main/java` (Maven/Gradle standard layout) |
+| `tests-root` | Looks for `src/test/java`, `test/`, `tests/` |
+| `language` | Detected from build files (`pom.xml`, `build.gradle`) and `.java` files |
+| `test-framework` | Checks build file dependencies for JUnit 5, JUnit 4, or TestNG |
+
+## Required Options
+
+- **`module-root`**: The source directory to optimize. Only code under this directory is discovered for optimization. For standard Maven/Gradle projects, this is `src/main/java`.
+- **`tests-root`**: The directory where your tests are located. Codeflash discovers existing tests and places generated replay tests here.
+- **`language`**: Must be set to `"java"` for Java projects.
+
+## Optional Options
+
+- **`test-framework`**: Test framework. Auto-detected from build dependencies. Supported values: `"junit5"` (default), `"junit4"`, `"testng"`.
+- **`disable-telemetry`**: Disable anonymized telemetry. Defaults to `false`.
+- **`git-remote`**: Git remote for pull requests. Defaults to `"origin"`.
+- **`ignore-paths`**: Paths within `module-root` to skip during optimization.
+
+## Multi-Module Projects
+
+For multi-module Maven/Gradle projects, place `codeflash.toml` at the project root and set `module-root` to the module you want to optimize:
+
+```text
+my-project/
+|- client/
+|  |- src/main/java/com/example/client/
+|  |- src/test/java/com/example/client/
+|- server/
+|  |- src/main/java/com/example/server/
+|- pom.xml
+|- codeflash.toml
+```
+
+```toml
+[tool.codeflash]
+module-root = "client/src/main/java"
+tests-root = "client/src/test/java"
+language = "java"
+```
+
+For non-standard layouts (like the Aerospike client where source is under `client/src/`), adjust paths accordingly:
+
+```toml
+[tool.codeflash]
+module-root = "client/src"
+tests-root = "test/src"
+language = "java"
+```
+
+## Tracer Options
+
+When using `codeflash optimize` to trace a Java program, these CLI options are available:
+
+| Option | Description | Default |
+|--------|------------|---------|
+| `--timeout` | Maximum time (seconds) for each tracing stage | No limit |
+| `--max-function-count` | Maximum captures per method | 100 |
+| `--trace-only` | Trace and generate replay tests without optimizing | `false` |
+
+Example with timeout:
+
+```bash
+codeflash optimize --timeout 30 java -jar target/my-app.jar --app-args
+```
+
+## Example
+
+### Standard Maven project
+
+```text
+my-app/
+|- src/
+|  |- main/java/com/example/
+|  |  |- App.java
+|  |  |- Utils.java
+|  |- test/java/com/example/
+|     |- AppTest.java
+|- pom.xml
+|- codeflash.toml
+```
+
+```toml
+[tool.codeflash]
+module-root = "src/main/java"
+tests-root = "src/test/java"
+language = "java"
+```
+
+### Gradle project
+
+```text
+my-lib/
+|- src/
+|  |- main/java/com/example/
+|  |- test/java/com/example/
+|- build.gradle
+|- codeflash.toml
+```
+
+```toml
+[tool.codeflash]
+module-root = "src/main/java"
+tests-root = "src/test/java"
+language = "java"
+```

docs/docs.json

@@ -26,7 +26,8 @@
             "group": "Getting Started",
             "pages": [
               "getting-started/local-installation",
-              "getting-started/javascript-installation"
+              "getting-started/javascript-installation",
+              "getting-started/java-installation"
             ]
           },
           {
@@ -45,6 +46,7 @@
             "pages": [
               "configuration/python",
               "configuration/javascript",
+              "configuration/java",
               "getting-the-best-out-of-codeflash"
             ]
           },

docs/getting-started/java-installation.mdx

@@ -0,0 +1,131 @@
+---
+title: "Java Installation"
+description: "Install and configure Codeflash for your Java project"
+icon: "java"
+sidebarTitle: "Java Setup"
+keywords:
+  [
+    "installation",
+    "java",
+    "maven",
+    "gradle",
+    "junit",
+    "junit5",
+    "tracing",
+  ]
+---
+
+Codeflash supports Java projects using Maven or Gradle build systems. It uses a two-stage tracing approach to capture method arguments and profiling data from running Java programs, then optimizes the hottest functions.
+
+### Prerequisites
+
+Before installing Codeflash, ensure you have:
+
+1. **Java 11 or above** installed
+2. **Maven or Gradle** as your build tool
+3. **A Java project** with source code under a standard directory layout
+
+Good to have (optional):
+
+1. **Unit tests** (JUnit 5 or JUnit 4) — Codeflash uses them alongside traced replay tests to verify correctness
+
+<Steps>
+<Step title="Install Codeflash CLI">
+
+Codeflash CLI is a Python tool. Install it with pip:
+
+```bash
+pip install codeflash
+```
+
+Or with uv:
+
+```bash
+uv pip install codeflash
+```
+
+</Step>
+<Step title="Initialize your project">
+
+Navigate to your Java project root (where `pom.xml` or `build.gradle` is) and run:
+
+```bash
+codeflash init
+```
+
+This will:
+- Detect your build tool (Maven/Gradle)
+- Find your source and test directories
+- Create a `codeflash.toml` configuration file
+
+</Step>
+<Step title="Verify setup">
+
+Check that the configuration looks correct:
+
+```bash
+cat codeflash.toml
+```
+
+You should see something like:
+
+```toml
+[tool.codeflash]
+module-root = "src/main/java"
+tests-root = "src/test/java"
+language = "java"
+```
+
+</Step>
+<Step title="Run your first optimization">
+
+Trace and optimize a running Java program:
+
+```bash
+codeflash optimize java -jar target/my-app.jar
+```
+
+Or with Maven:
+
+```bash
+codeflash optimize mvn exec:java -Dexec.mainClass="com.example.Main"
+```
+
+Codeflash will:
+1. Profile your program using JFR (Java Flight Recorder)
+2. Capture method arguments using a bytecode instrumentation agent
+3. Generate JUnit replay tests from the captured data
+4. Rank functions by performance impact
+5. Optimize the most impactful functions
+
+</Step>
+</Steps>
+
+## How it works
+
+Codeflash uses a **two-stage tracing** approach for Java:
+
+1. **Stage 1 — JFR Profiling**: Runs your program with Java Flight Recorder enabled to collect accurate method-level CPU profiling data. JFR has ~1% overhead and doesn't affect JIT compilation.
+
+2. **Stage 2 — Argument Capture**: Runs your program again with a bytecode instrumentation agent that captures method arguments using Kryo serialization. Arguments are stored in an SQLite database.
+
+The traced data is used to generate **JUnit replay tests** that exercise your functions with real-world inputs. Codeflash uses these tests alongside any existing unit tests to verify correctness and benchmark optimization candidates.
+
+<Info>
+Your program runs **twice** — once for profiling, once for argument capture. This separation ensures profiling data isn't distorted by serialization overhead.
+</Info>
+
+## Supported build tools
+
+| Build Tool | Detection | Test Execution |
+|-----------|-----------|---------------|
+| **Maven** | `pom.xml` | Maven Surefire plugin |
+| **Gradle** | `build.gradle` / `build.gradle.kts` | Gradle test task |
+
+## Supported test frameworks
+
+| Framework | Support Level |
+|-----------|-------------|
+| **JUnit 5** | Full support (default) |
+| **JUnit 4** | Full support |
+| **TestNG** | Basic support |

docs/optimizing-with-codeflash/trace-and-optimize.mdx

@@ -15,6 +15,10 @@ keywords:
     "typescript",
     "jest",
     "vitest",
+    "java",
+    "jfr",
+    "maven",
+    "gradle",
   ]
 ---
 
@@ -52,6 +56,26 @@ codeflash optimize --vitest
 codeflash optimize --language javascript script.js
 ```
 </Tab>
+<Tab title="Java">
+To trace and optimize a running Java program, replace your `java` command with `codeflash optimize java`:
+
+```bash
+# JAR application
+codeflash optimize java -jar target/my-app.jar --app-args
+
+# Class with classpath
+codeflash optimize java -cp target/classes com.example.Main
+
+# Maven exec
+codeflash optimize mvn exec:java -Dexec.mainClass="com.example.Main"
+```
+
+For long-running programs (servers, benchmarks), use `--timeout` to limit each tracing stage:
+
+```bash
+codeflash optimize --timeout 30 java -jar target/my-app.jar
+```
+</Tab>
 </Tabs>
 
 The `codeflash optimize` command creates high-quality optimizations, making it ideal when you need to optimize a workflow or script. The initial tracing process can be slow, so try to limit your script's runtime to under 1 minute for best results.
@@ -194,5 +218,57 @@ The JavaScript tracer uses Babel instrumentation to capture function calls durin
    - `--max-function-count`: Maximum traces per function (default: 256).
    - `--only-functions`: Comma-separated list of function names to trace.
 
+</Tab>
+<Tab title="Java">
+
+The Java tracer uses a **two-stage approach**: JFR (Java Flight Recorder) for accurate profiling, then a bytecode instrumentation agent for argument capture.
+
+1. **Trace and optimize a Java program**
+
+   Replace your `java` command with `codeflash optimize java`:
+
+   ```bash
+   # JAR application
+   codeflash optimize java -jar target/my-app.jar --app-args
+
+   # Class with classpath
+   codeflash optimize java -cp target/classes com.example.Main
+   ```
+
+   Codeflash will run your program twice (once for profiling, once for argument capture), generate JUnit replay tests, then optimize the most impactful functions.
+
+2. **Long-running programs**
+
+   For servers, benchmarks, or programs that don't terminate on their own, use `--timeout` to limit each tracing stage:
+
+   ```bash
+   codeflash optimize --timeout 30 java -jar target/my-benchmark.jar
+   ```
+
+   Each stage runs for at most 30 seconds, then the program is terminated and captured data is processed.
+
+3. **Trace only (no optimization)**
+
+   ```bash
+   codeflash optimize --trace-only java -jar target/my-app.jar
+   ```
+
+   This generates replay tests in `src/test/java/codeflash/replay/` without running the optimizer.
+
+   More Options:
+
+   - `--timeout`: Maximum time (seconds) for each tracing stage.
+   - `--max-function-count`: Maximum captures per method (default: 100).
+
+<Info>
+**How the Java tracer works:**
+
+- **Stage 1 (JFR)**: Runs your program with Java Flight Recorder enabled. JFR is built into the JVM (Java 11+), has ~1% overhead, and doesn't interfere with JIT compilation. This produces accurate method-level CPU profiling data.
+
+- **Stage 2 (Agent)**: Runs your program with a bytecode instrumentation agent injected via `JAVA_TOOL_OPTIONS`. The agent intercepts method entry points, serializes arguments using Kryo, and writes them to an SQLite database. A 500ms timeout per serialization prevents hangs on complex object graphs.
+
+- **Replay Tests**: Generated JUnit 5 test classes that deserialize captured arguments and invoke the original methods via reflection. These tests exercise your code with real-world inputs.
+</Info>
+
 </Tab>
 </Tabs>