From d00a21b02c9dba5eb988271281d63dbb70bc1b35 Mon Sep 17 00:00:00 2001
From: {{Your Name}} <{{your.email@example.com}}>
Date: Thu, 7 May 2026 13:28:49 -0700
Subject: [PATCH] docs: expand Development section with build process
 documentation

Add prerequisites, build commands, artifact descriptions, run
instructions, and code formatting guidance. Fix stray 'mavern have'
typo in the original Development section.

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 48 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 5945f76..bcd267e 100644
--- a/README.md
+++ b/README.md
@@ -22,12 +22,58 @@ jvm --help
 
 ## Development
 
-To build the project simply run:
+### Prerequisites
+
+- **Java 11+** — required to compile and run (`JAVA_HOME` must be set)
+- **Maven** — provided via the included wrapper (`mvnw` / `mvnw.cmd`), no separate install needed
+
+### Building
+
+Full build with formatting and tests:
 
 ```shell
 ./mvnw spotless:apply clean verify
 ```
- mavern have
+
+Quick build, skipping tests:
+
+```shell
+./mvnw clean package -DskipTests
+```
+
+The build produces two JARs in `target/`:
+
+- `jvm-<version>.jar` — thin JAR (no bundled dependencies)
+- `jvm-<version>-cli.jar` — fat JAR, runnable directly
+
+### Running the Built Artifact
+
+```shell
+java -jar target/jvm-<version>-cli.jar --help
+java -jar target/jvm-<version>-cli.jar --version
+java -jar target/jvm-<version>-cli.jar list
+```
+
+Or use the assembled launcher from `target/binary/bin/`:
+
+```shell
+# Linux/macOS
+./target/binary/bin/jvm --help
+# Windows
+target\binary\bin\jvm.bat --help
+```
+
+### Code Formatting
+
+The project uses [Spotless](https://github.com/diffplug/spotless) with Google Java Format (AOSP style).
+
+```shell
+# Apply formatting
+./mvnw spotless:apply
+# Check without modifying
+./mvnw spotless:check
+```
+
 ### Building Native Executables
 
 The project supports building native executables using GraalVM. This creates a standalone binary with faster startup time and lower memory footprint.