From 49a6dacd7565ed1407c49a28412894f3b5e1b6ae Mon Sep 17 00:00:00 2001
From: Alexis Sellier <alexis@radicle.xyz>
Date: Sun, 12 Mar 2023 16:30:20 +0100
Subject: [PATCH] Flesh out `README`

---
 HACKING.md |  3 +++
 README.md  | 47 ++++++++++++++++++++++++++++++++++++++---------
 2 files changed, 41 insertions(+), 9 deletions(-)
 create mode 100644 HACKING.md

diff --git a/HACKING.md b/HACKING.md
new file mode 100644
index 00000000..eabe4347
--- /dev/null
+++ b/HACKING.md
@@ -0,0 +1,3 @@
+# HACKING
+
+*Work in progress.*
diff --git a/README.md b/README.md
index dd7f9f5b..2c7b1002 100644
--- a/README.md
+++ b/README.md
@@ -2,17 +2,46 @@
 
 *Radicle Heartwood Protocol & Stack*
 
-Heartwood is in the early development phase and is not yet ready for use.
+Heartwood is the third iteration of the Radicle Protocol, a powerful
+peer-to-peer code collaboration and publishing stack. The repository contains a
+full implemention of Heartwood, complete with a user-friendly command-line
+interface (`rad`) and network daemon (`radicle-node`).
+
+Radicle was designed to be a secure, decentralized and powerful alternative to
+code forges such as GitHub and GitLab that preserves user sovereignty
+and freedom.
 
 ## Installation
 
-```
-# Command line tools
-$ cargo install --locked --path ./radicle-cli
+**Requirements**
 
-# The radicle node
-$ cargo install --locked --path ./radicle-node
+* *Linux* or *Unix* based operating system.
+* Git 2.34 or later
+* OpenSSH 9.1 or later with `ssh-agent`
 
-# Git tool to support the 'rad://' remote scheme
-$ cargo install --locked --path ./radicle-remote-helper
-```
+### 📦 From source
+
+> Requires the Rust toolchain.
+
+You can install the Radicle stack from source, by running the following
+commands from inside this repository:
+
+    cargo install --path radicle-cli --force --locked
+    cargo install --path radicle-node --force --locked
+    cargo install --path radicle-remote-helper --force --locked
+
+Or directly from our seed node:
+
+    cargo install --force --locked --git https://seed.radicle.xyz/z3gqcJUoA1n9HaHKufZs5FCSGazv5.git \
+        radicle-cli radicle-node radicle-remote-helper
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [HACKING.md](HACKING.md) for an
+introduction to contributing to Radicle.
+
+## License
+
+Radicle is distributed under the terms of both the MIT license and the Apache License (Version 2.0).
+
+See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT) for details.