From c0baaf712933a6c258513d134bba6631426ab8fe Mon Sep 17 00:00:00 2001
From: Eric T <tchepane@hey.com>
Date: Tue, 19 Aug 2025 16:11:09 +0100
Subject: [PATCH 1/2] docs: streamline README and move setup instructions

---
 README.md               | 50 ++--------------------------------------
 docs/GETTING_STARTED.md | 51 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 53 insertions(+), 48 deletions(-)
 create mode 100644 docs/GETTING_STARTED.md

diff --git a/README.md b/README.md
index afc1de39f..9fa97e474 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,4 @@
 # nostr-java
-[![CI](https://github.com/tcheeric/nostr-java/actions/workflows/ci.yml/badge.svg)](https://github.com/tcheeric/nostr-java/actions/workflows/ci.yml)
-[![codecov](https://codecov.io/gh/tcheeric/nostr-java/branch/main/graph/badge.svg)](https://codecov.io/gh/tcheeric/nostr-java)
-[![GitHub release](https://img.shields.io/github/v/release/tcheeric/nostr-java)](https://github.com/tcheeric/nostr-java/releases)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 `nostr-java` is a Java SDK for the [Nostr](https://github.com/nostr-protocol/nips) protocol. It provides utilities for creating, signing and publishing Nostr events to relays.
 
@@ -10,54 +6,12 @@
 - Maven
 - Java 21+
 
-## Getting Started
-Clone the repository and build the modules. Installing them locally allows you to add the artifacts as dependencies in your own projects:
-
-```bash
-$ git clone https://github.com/tcheeric/nostr-java.git
-$ cd nostr-java
-$ ./mvnw clean install
-```
-
-You can also consume published artifacts from our Maven repository instead of building from source.
-
-### Maven
-
-```xml
-<repositories>
-  <repository>
-    <id>nostr-java</id>
-    <url>https://maven.398ja.xyz/releases</url>
-  </repository>
-</repositories>
-
-<dependency>
-  <groupId>xyz.tcheeric</groupId>
-  <artifactId>nostr-java-api</artifactId>
-  <version>[VERSION]</version>
-</dependency>
-```
-
-Snapshot builds are available at `https://maven.398ja.xyz/snapshots`.
-
-### Gradle
-
-```gradle
-repositories {
-    maven { url 'https://maven.398ja.xyz/releases' }
-}
-
-dependencies {
-    implementation 'xyz.tcheeric:nostr-java-api:[VERSION]'
-}
-```
-
-Replace `[VERSION]` with the latest release number from the [releases page](https://github.com/tcheeric/nostr-java/releases).
+See [docs/GETTING_STARTED.md](docs/GETTING_STARTED.md) for installation and usage instructions.
 
 See [`docs/CODEBASE_OVERVIEW.md`](docs/CODEBASE_OVERVIEW.md) for details about running tests and contributing.
 
 ## Examples
-Example usages are located in the [`nostr-java-examples`](./nostr-java-examples) module. Additional demonstrations can be found in [nostr-client](https://github.com/tcheeric/nostr-client) and [SuperConductor](https://github.com/avlo/superconductor).
+Examples are located in the [`nostr-java-examples`](./nostr-java-examples) module.
 
 ## Supported NIPs
 The API currently implements the following [NIPs](https://github.com/nostr-protocol/nips):
diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md
new file mode 100644
index 000000000..1d85c523d
--- /dev/null
+++ b/docs/GETTING_STARTED.md
@@ -0,0 +1,51 @@
+# Getting Started
+
+## Prerequisites
+- Maven
+- Java 21+
+
+## Building from Source
+
+```bash
+git clone https://github.com/tcheeric/nostr-java.git
+cd nostr-java
+./mvnw clean install
+```
+
+## Using Maven
+
+Artifacts are published to `https://maven.398ja.xyz/releases`:
+
+```xml
+<repositories>
+  <repository>
+    <id>nostr-java</id>
+    <url>https://maven.398ja.xyz/releases</url>
+  </repository>
+</repositories>
+
+<dependency>
+  <groupId>xyz.tcheeric</groupId>
+  <artifactId>nostr-java-api</artifactId>
+  <version>[VERSION]</version>
+</dependency>
+```
+
+Snapshot builds are available at `https://maven.398ja.xyz/snapshots`.
+
+## Using Gradle
+
+```gradle
+repositories {
+    maven { url 'https://maven.398ja.xyz/releases' }
+}
+
+dependencies {
+    implementation 'xyz.tcheeric:nostr-java-api:[VERSION]'
+}
+```
+
+Replace `[VERSION]` with the latest release number from the [releases page](https://github.com/tcheeric/nostr-java/releases).
+
+Examples are available in the [`nostr-java-examples`](../nostr-java-examples) module.
+

From a93ae7b501e7cee1ef26f7ea7bf883443a01af8f Mon Sep 17 00:00:00 2001
From: Eric T <tchepane@hey.com>
Date: Tue, 19 Aug 2025 17:14:55 +0100
Subject: [PATCH 2/2] docs: restore badges

---
 README.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/README.md b/README.md
index 9fa97e474..aff781ee6 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,8 @@
 # nostr-java
+[![CI](https://github.com/tcheeric/nostr-java/actions/workflows/ci.yml/badge.svg)](https://github.com/tcheeric/nostr-java/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/tcheeric/nostr-java/branch/main/graph/badge.svg)](https://codecov.io/gh/tcheeric/nostr-java)
+[![GitHub release](https://img.shields.io/github/v/release/tcheeric/nostr-java)](https://github.com/tcheeric/nostr-java/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 `nostr-java` is a Java SDK for the [Nostr](https://github.com/nostr-protocol/nips) protocol. It provides utilities for creating, signing and publishing Nostr events to relays.