diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9e44c93
--- /dev/null
+++ b/README.md
@@ -0,0 +1,108 @@
+[](https://opensource.org/licenses/Apache-2.0)
+[](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html)
+[](https://github.com/rife2/bld/releases/latest)
+[](https://maven-badges.herokuapp.com/maven-central/com.uwyn.rife2/bld)
+[](https://s01.oss.sonatype.org/content/repositories/snapshots/com/uwyn/rife2/bld/)
+[](https://github.com/rife2/bld/actions/workflows/bld.yml)
+[](https://github.com/rife2/rife2/actions/workflows/bld.yml)
+
+
+
+
+
+# What is bld?
+
+`bld` is a new build system that allows you to write your build logic in pure
+Java.
+
+`bld` was created because we're not really interested in build tools. We use
+them because we have to, but we'd rather just get on with coding the real stuff.
+
+`bld` is designed with the following principles in mind:
+
+* tasks don't happen without you telling them to happen
+* no auto-magical behavior, task behavior is explicit and API-defined
+* managing libs yourself is fine, having that automated also, or mix and match
+* build logic is written in Java, with all the advantages of Java
+* standard collection of Java-centric tasks for common operations
+* bld is distributed in a single jar, if you have the jar, you have the build system
+
+# Designed for modern Java
+
+bld relies on Java 17 and leverages many of the features that this version of
+Java provides. Thanks to the modern language constructs, your Java build logic
+ends up looking very concise, is easily readable and understood by any IDE.
+You automatically get support for auto-completion and javadoc documentation,
+and you can split your build logic into multiple files and classes when you outgrow a single file.
+
+Here is a complete bld file for a Java application using JUnit 5 for its tests.
+Nothing else is needed to be able to run it, test it and distribute it:
+
+```java
+package com.example;
+
+import rife.bld.Project;
+import java.util.List;
+import static rife.bld.dependencies.Repository.*;
+import static rife.bld.dependencies.Scope.*;
+
+public class MyappBuild extends Project {
+ public MyappBuild() {
+ pkg = "com.example";
+ name = "Myapp";
+ mainClass = "com.example.MyappMain";
+ version = version(0,1,0);
+
+ downloadSources = true;
+ repositories = List.of(MAVEN_CENTRAL, RIFE2_RELEASES);
+ scope(test)
+ .include(dependency("org.junit.jupiter",
+ "junit-jupiter",
+ version(5,9,2)))
+ .include(dependency("org.junit.platform",
+ "junit-platform-console-standalone",
+ version(1,9,2)));
+ }
+
+ public static void main(String[] args) {
+ new MyappBuild().start(args);
+ }
+}
+```
+
+
+> **NOTE:** `bld` supports different ways to describe dependencies,
+> `dependency("com.uwyn.rife2", "rife2", version(1,6,3))` can for instance also
+> be written as `dependency("com.uwyn.rife2:rife2:1.6.3")`. Which format you use,
+> is a matter of personal taste.
+
+# Where does `bld` fit?
+
+From a very high level, build tools can be organized in a matrix:
+* either your tool is declarative or in code
+* either your tool first describes a plan or immediately executes a plan
+
+
+| | Declarative | Code | Describes | Immediate |
+|--------|-------------|------|-----------|-----------|
+| Maven | X | | X | |
+| Gradle | | X | X | |
+| `bld` | | X | | X |
+
+Writing your build logic in the same language as your application (Java),
+significantly reduces the cognitive load, and taking actions immediately
+without having to mentally construct a described plan, makes it easier to
+reason about your build.
+
+# Find out more
+
+`bld` lets your build logic get out of the way so that you can focus on writing
+applications.
+
+If you have any questions, suggestions, ideas or just want to chat, feel free
+to post on the [forums](https://github.com/rife2/bld/discussions), to join
+me on [Discord](https://discord.gg/DZRYPtkb6J) or to connect with me on
+[Mastodon](https://uwyn.net/@gbevin).
+
+**Read more in the [full documentation](https://github.com/rife2/bld/wiki)
+and [bld Javadocs](https://rife2.github.io/bld/).**