diff --git a/docs/getting-started/java-installation.mdx b/docs/getting-started/java-installation.mdx
index a75e1f0b7..d824a3a3b 100644
--- a/docs/getting-started/java-installation.mdx
+++ b/docs/getting-started/java-installation.mdx
@@ -15,7 +15,9 @@ keywords:
   ]
 ---
 
-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.
+Codeflash supports optimizing Java projects using Maven or Gradle build systems. It works in two main ways:
+1. Codeflash can optimize new java code written in a Pull Request through Github Actions.
+2. Codeflash can optimize real workloads end to end. It uses a two-stage tracing approach to capture method arguments and profiling data from running Java program, then optimizes the hottest functions with that data.
 
 ### Prerequisites
 
@@ -32,16 +34,16 @@ Good to have (optional):
 <Steps>
 <Step title="Install Codeflash CLI">
 
-Codeflash CLI is a Python tool. Install it with pip:
+Codeflash uses Python to run its CLI. You can use uv as a package manager and installer for Python programs.
+To install uv, run the following or [see these instructions](https://docs.astral.sh/uv/getting-started/installation/)
+
+  ```bash
+  curl -LsSf https://astral.sh/uv/install.sh | sh
+  ```
+Then install Codeflash as a uv tool.
 
 ```bash
-pip install codeflash
-```
-
-Or with uv:
-
-```bash
-uv pip install codeflash
+uv tool install codeflash
 ```
 
 </Step>
@@ -56,30 +58,12 @@ 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"
-```
+- Update your pom.xml or gradle settings with codeflash java library. The java library instruments your code and verifies correctness.
 
 </Step>
 <Step title="Run your first optimization">
 
-Trace and optimize a running Java program:
+Trace and optimize a Java program:
 
 ```bash
 codeflash optimize java -jar target/my-app.jar
@@ -94,27 +78,13 @@ 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
+3. Generate JUnit replay tests from the captured data to create a micro-benchmark.
 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 |