Merge pull request #2019 from codeflash-ai/cf-1090-java-documentation-gaps

docs: fix Java documentation gaps across 5 pages

docs/codeflash-concepts/how-codeflash-works.mdx

@@ -3,20 +3,20 @@ title: "How Codeflash Works"
 description: "Understand Codeflash's generate-and-verify approach to code optimization and correctness verification"
 icon: "gear"
 sidebarTitle: "How It Works"
-keywords: ["architecture", "verification", "correctness", "testing", "optimization", "LLM", "benchmarking", "javascript", "typescript", "python"]
+keywords: ["architecture", "verification", "correctness", "testing", "optimization", "LLM", "benchmarking", "javascript", "typescript", "python", "java"]
 ---
 # How Codeflash Works
 
 Codeflash follows a "generate and verify" approach to optimize code. It uses LLMs to generate optimizations, then it rigorously verifies if those optimizations are indeed
 faster and if they have the same behavior. The basic unit of optimization is a function—Codeflash tries to speed up the function, and tries to ensure that it still behaves the same way. This way if you merge the optimized code, it simply runs faster without breaking any functionality.
 
-Codeflash supports **Python**, **JavaScript**, and **TypeScript** projects.
+Codeflash supports **Python**, **JavaScript**, **TypeScript**, and **Java** projects.
 
 ## Analysis of your code
 
 Codeflash scans your codebase to identify all available functions. It locates existing unit tests in your projects and maps which functions they test. When optimizing a function, Codeflash runs these discovered tests to verify nothing has broken.
 
-For Python, code analysis uses `libcst` and `jedi`. For JavaScript/TypeScript, it uses `tree-sitter` for AST parsing.
+For Python, code analysis uses `libcst` and `jedi`. For JavaScript/TypeScript and Java, it uses `tree-sitter` for AST parsing.
 
 #### What kind of functions can Codeflash optimize?
 
@@ -25,7 +25,7 @@ Codeflash supports optimizing async functions in all supported languages.
 
 #### Test Discovery
 
-Codeflash discovers tests that directly call the target function in their test body. For Python, it finds pytest and unittest tests. For JavaScript/TypeScript, it finds Jest and Vitest test files.
+Codeflash discovers tests that directly call the target function in their test body. For Python, it finds pytest and unittest tests. For JavaScript/TypeScript, it finds Jest and Vitest test files. For Java, it finds JUnit 5, JUnit 4, and TestNG test classes.
 
 To discover tests that indirectly call the function, you can use the Codeflash Tracer. The Tracer analyzes your test suite and identifies all tests that eventually call a function.
 
@@ -54,12 +54,12 @@ We recommend manually reviewing the optimized code since there might be importan
 
 Codeflash generates two types of tests:
 
-- **LLM Generated tests** - Codeflash uses LLMs to create several regression test cases that cover typical function usage, edge cases, and large-scale inputs to verify both correctness and performance. This works for Python, JavaScript, and TypeScript.
+- **LLM Generated tests** - Codeflash uses LLMs to create several regression test cases that cover typical function usage, edge cases, and large-scale inputs to verify both correctness and performance. This works for Python, JavaScript, TypeScript, and Java.
 - **Concolic coverage tests** - Codeflash uses state-of-the-art concolic testing with an SMT Solver (a theorem prover) to explore execution paths and generate function arguments. This aims to maximize code coverage for the function being optimized. Currently, this feature only supports Python (pytest).
 
 ## Code Execution
 
-Codeflash runs tests for the target function on your machine. For Python, it uses pytest or unittest. For JavaScript/TypeScript, it uses Jest or Vitest. Running on your machine ensures access to your environment and dependencies, and provides accurate performance measurements since runtime varies by system.
+Codeflash runs tests for the target function on your machine. For Python, it uses pytest or unittest. For JavaScript/TypeScript, it uses Jest or Vitest. For Java, it uses Maven Surefire or Gradle's test task. Running on your machine ensures access to your environment and dependencies, and provides accurate performance measurements since runtime varies by system.
 
 #### Performance benchmarking
 

docs/getting-started/java-installation.mdx

@@ -47,7 +47,38 @@ uv tool install codeflash
 ```
 
 </Step>
-<Step title="Initialize your project">
+<Step title="Authenticate with Codeflash">
+
+Codeflash uses cloud-hosted AI models. You need to authenticate before running any commands.
+
+**Option A: Browser login (recommended)**
+
+```bash
+codeflash auth login
+```
+
+This opens your browser to sign in with your GitHub account. Your API key is saved automatically to your shell profile.
+
+If you're on a remote server without a browser, a URL will be displayed that you can open on any device.
+
+**Option B: API key**
+
+1. Visit the [Codeflash Web App](https://app.codeflash.ai/) and sign up with your GitHub account (free tier available)
+2. Navigate to the [API Key](https://app.codeflash.ai/app/apikeys) page to generate your key
+3. Set it as an environment variable:
+
+```bash
+export CODEFLASH_API_KEY="your-api-key-here"
+```
+
+Add this to your shell profile (`~/.bashrc`, `~/.zshrc`) so it persists across sessions.
+
+<Info>
+If you skip this step, `codeflash init` will prompt you to authenticate interactively.
+</Info>
+
+</Step>
+<Step title="Initialize your project (recommended)">
 
 Navigate to your Java project root (where `pom.xml` or `build.gradle` is) and run:
 
@@ -55,10 +86,33 @@ Navigate to your Java project root (where `pom.xml` or `build.gradle` is) and ru
 codeflash init
 ```
 
-This will:
-- Detect your build tool (Maven/Gradle)
-- Find your source and test directories
-- Write Codeflash configuration to your `pom.xml` properties (Maven) or `gradle.properties` (Gradle)
+The init command will:
+1. **Auto-detect your project** — find your build tool, source root (e.g., `src/main/java`), test root (e.g., `src/test/java`), and test framework
+2. **Confirm settings** — show the detected values and ask if you want to change anything
+3. **Configure formatter** — let you set up a code formatter (e.g., Spotless, google-java-format)
+4. **Install GitHub App** — offer to set up the [Codeflash GitHub App](https://github.com/apps/codeflash-ai/installations/select_target) for automatic PR creation (see next step)
+5. **Install GitHub Actions** — offer to add a CI workflow for automated optimization on PRs
+
+Only non-default settings are written to your `pom.xml` properties (Maven) or `gradle.properties` (Gradle). For standard layouts, no config changes are needed.
+
+<Info>
+**Can I skip init?** Yes. For standard Maven/Gradle projects, Codeflash auto-detects your project structure from `pom.xml` or `build.gradle` at runtime. If you're already authenticated and your project uses a standard layout (`src/main/java`, `src/test/java`), you can skip straight to optimizing.
+
+Init is recommended because it also sets up the GitHub App and Actions workflow, and lets you override paths for non-standard project layouts (e.g., multi-module projects where source is under `client/src/`).
+</Info>
+
+</Step>
+<Step title="Install the Codeflash GitHub App (recommended)">
+
+To have Codeflash create pull requests with optimizations automatically, install the GitHub App:
+
+[Install Codeflash GitHub App](https://github.com/apps/codeflash-ai/installations/select_target)
+
+Select the repositories you want Codeflash to optimize. This allows the codeflash-ai bot to open PRs with optimization suggestions in your repository.
+
+<Info>
+If you prefer to try Codeflash locally first, you can skip this step and use the `--no-pr` flag to apply optimizations directly to your local files (see next step).
+</Info>
 
 </Step>
 <Step title="Run your first optimization">
@@ -69,6 +123,12 @@ Optimize a specific function:
 codeflash --file src/main/java/com/example/Utils.java --function myMethod
 ```
 
+If you installed the GitHub App, Codeflash will create a pull request with the optimization. If you haven't installed the app yet, or prefer to review changes locally first, add `--no-pr`:
+
+```bash
+codeflash --file src/main/java/com/example/Utils.java --function myMethod --no-pr
+```
+
 Or optimize all functions in your project:
 
 ```bash
@@ -80,7 +140,7 @@ Codeflash will:
 2. Generate tests and optimization candidates using AI
 3. Verify correctness by running tests (JUnit 5, JUnit 4, or TestNG)
 4. Benchmark performance improvements
-5. Create a pull request with the optimization (if the GitHub App is installed)
+5. Create a pull request with the optimization (or apply locally with `--no-pr`)
 
 For advanced workflow tracing (profiling a running Java program), see [Trace & Optimize](/optimizing-with-codeflash/trace-and-optimize).
 

docs/optimizing-with-codeflash/codeflash-all.mdx

@@ -3,7 +3,7 @@ title: "Optimize Your Entire Codebase"
 description: "Automatically optimize all codepaths in your project with Codeflash's comprehensive analysis"
 icon: "database"
 sidebarTitle: "Optimize Entire Codebase"
-keywords: ["codebase optimization", "all functions", "batch optimization", "github app", "checkpoint", "recovery", "javascript", "typescript", "python"]
+keywords: ["codebase optimization", "all functions", "batch optimization", "github app", "checkpoint", "recovery", "javascript", "typescript", "python", "java"]
 ---
 
 # Optimize your entire codebase
@@ -45,6 +45,11 @@ codeflash --all path/to/dir
   codeflash optimize --trace-only --vitest ; codeflash --all
   ```
   </Tab>
+  <Tab title="Java">
+  ```bash
+  codeflash optimize --timeout 60 java -cp target/classes com.example.Main ; codeflash --all
+  ```
+  </Tab>
   </Tabs>
 
   This runs your test suite, traces all the code covered by your tests, ensuring higher correctness guarantees

docs/optimizing-with-codeflash/one-function.mdx

@@ -93,5 +93,7 @@ codeflash --file path/to/your/file.ts --function ClassName.methodName
 ```bash
 codeflash --file src/main/java/com/example/Utils.java --function methodName
 ```
+
+In Java, use just the method name — no `ClassName.` prefix is needed. Codeflash discovers the method by name within the specified file.
 </Tab>
 </Tabs>

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

@@ -60,12 +60,12 @@ codeflash optimize --language javascript script.js
 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
+# Class with classpath (recommended — works with any compiled project)
 codeflash optimize java -cp target/classes com.example.Main
 
+# Executable JAR (requires maven-jar-plugin or equivalent with Main-Class manifest)
+codeflash optimize java -jar target/my-app.jar --app-args
+
 # Maven exec
 codeflash optimize mvn exec:java -Dexec.mainClass="com.example.Main"
 ```
@@ -73,7 +73,7 @@ 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
+codeflash optimize --timeout 30 java -cp target/classes com.example.Main
 ```
 </Tab>
 </Tabs>
@@ -228,13 +228,15 @@ The Java tracer uses a **two-stage approach**: JFR (Java Flight Recorder) for ac
    Replace your `java` command with `codeflash optimize java`:
 
    ```bash
-   # JAR application
-   codeflash optimize java -jar target/my-app.jar --app-args
-
-   # Class with classpath
+   # Class with classpath (recommended — works with any compiled project)
    codeflash optimize java -cp target/classes com.example.Main
+
+   # Executable JAR (requires maven-jar-plugin or equivalent with Main-Class manifest)
+   codeflash optimize java -jar target/my-app.jar --app-args
    ```
 
+   The `-cp` approach works with any project after `mvn compile` or `gradle build`. The `-jar` approach requires your project to produce an executable JAR with a `Main-Class` entry in the manifest — this is not the default Maven behavior.
+
    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**
@@ -242,7 +244,7 @@ The Java tracer uses a **two-stage approach**: JFR (Java Flight Recorder) for ac
    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
+   codeflash optimize --timeout 30 java -cp target/classes com.example.Main
    ```
 
    Each stage runs for at most 30 seconds, then the program is terminated and captured data is processed.