1 files changed, 91 insertions, 0 deletions
diff --git a/modules/templates/java/README.md b/modules/templates/java/README.md
new file mode 100644
index 0000000..7cc5735
--- /dev/null
+++ b/modules/templates/java/README.md
@@ -0,0 +1,91 @@
+# Java Development Environment
+
+A simple Nix Flake providing a reproducible Java development environment.
+
+## Included Tools
+
+* **JDK 21** – Java compiler and runtime
+* **Maven** – Dependency management and project build tool
+* **Gradle** – Alternative build system
+* **JDT Language Server** – Language server used by many editors (Neovim, VS Code, Helix, etc.)
+
+## Usage
+
+Enter the development shell:
+
+```bash
+nix develop
+```
+
+When the shell starts, it will display the installed Java version and create an `out/` directory for compiled classes if it doesn't already exist.
+
+## Helper Commands
+
+The shell provides a few convenience aliases for small Java projects.
+
+### `jbuild`
+
+Compiles every Java source file under `src/` into the `out/` directory.
+
+```bash
+jbuild
+```
+
+Equivalent to:
+
+```bash
+find src -name "*.java" | xargs javac -d out
+```
+
+---
+
+### `jrun`
+
+Builds the project and runs:
+
+```text
+src.Main
+```
+
+```bash
+jrun
+```
+
+This assumes your application's entry point is `src.Main`.
+
+---
+
+### `jclean`
+
+Removes compiled output.
+
+```bash
+jclean
+```
+
+## Project Layout
+
+This template assumes a simple project structure:
+
+```text
+.
+├── flake.nix
+├── src/
+│   └── Main.java
+└── out/
+```
+
+For larger projects, consider using Maven or Gradle instead of the helper aliases.
+
+## Customization
+
+This template is intended as a starting point. You can easily modify it to:
+
+* use a different JDK version
+* add testing frameworks (JUnit, TestNG)
+* include formatting and linting tools
+* add debugging utilities
+* add database or web development dependencies
+
+Because everything is defined in the flake, the development environment remains reproducible across Linux, macOS, and other supported platforms.
+