diff --git a/README.md b/README.md
index 4b1448c..ca55a27 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,4 @@
+
@@ -20,7 +21,6 @@
-
> The Web, long centralized, must decentralize; Long decentralized, must centralize.
## Overview
@@ -34,6 +34,25 @@ Pubky-core combines a [censorship resistant public-key based alternative to DNS]
## Getting started
-> [!WARNING]
-> Pubky is still under heavy development and should be considered an alpha software.
-> Features might be added, removed, or changed. Data might be lost.
+This repository contains a [Homeserver](./pubky-homeserver), and a [Client](./pubky) (both Rust and JS wasm bindings).
+You can a run a local homeserver using `cargo run` with more instructions in the README.
+Check the [Examples](./examples) directory for small feature-focesed examples of how to use the Pubky client.
+
+### JavaScript
+If you prefer to use JavaScript in NodeJs/Browser or any runtime with Wasm support, you can either install from npm [`@synonymdev/pubky`](https://www.npmjs.com/package/@synonymdev/pubky)
+or build the bindings yourself:
+```bash
+cd pubky/pkg
+npm i
+npm run build
+```
+
+#### Testing
+There are unit tests for the JavaScript bindings in both NodeJs and headless web browser, but first you need to run a local temporary Homeserver
+```bash
+npm run testnet
+```
+Then in a different terminal window:
+```bash
+npm test
+```
diff --git a/pubky-homeserver/README.md b/pubky-homeserver/README.md
index 7b884d5..f222f7e 100644
--- a/pubky-homeserver/README.md
+++ b/pubky-homeserver/README.md
@@ -1,5 +1,7 @@
# Pubky Homeserver
+A pubky-core homeserver that acts as users' agent on the Internet, providing data availability and more.more.more.more.
+
## Usage
Use `cargo run`
diff --git a/pubky/README.md b/pubky/README.md
new file mode 100644
index 0000000..087ffc2
--- /dev/null
+++ b/pubky/README.md
@@ -0,0 +1,4 @@
+# Pubky
+
+Rust implementation implementation of [Pubky](https://github.com/pubky/pubky-core) client.
+