diff --git a/README.md b/README.md
index 21bc758..58574e1 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,149 @@
-# dart-torchat
 
-A dart implementation of a full node that can run on any device with any architecture.
\ No newline at end of file
+# TorChat Dart Node
+
+<p align="center">
+<a href="https://haveno.com"><img src="https://foss.haveno.com/tor-project/torchat/raw/branch/main/assets/images/torchat-compressed-rounded.png" width=275 /></a>
+</p>
+
+----
+
+A full, cross-platform **Tor/Arti-powered** TorChat written 100 % in Dart.  
+Spin it up on Windows, macOS, Linux—even mobile or Raspberry Pi—no C tool-chain, no hassle.
+
+> **TL;DR**  
+> `dart pub global activate whisper_node`  
+> `whisper_node run`  
+> Voilà: a fully-functional relay + client with gRPC endpoints and a sweet high-level SDK.
+
+---
+
+## 🌐 What Is It?
+
+TorChat-Dart is the **reference implementation** of the TorChat protocol in pure Dart.  
+It exposes:
+
+| Layer | Purpose |
+|-------|---------|
+| **gRPC API** | Full power, language-agnostic. Auto-generated protobuf docs & stubs. |
+| **Dart SDK** | High-level classes (`WhisperClient`, `WhisperRelay`, `GroupChat`, …). |
+| **Tor/Arti wrapper** | Boots a hidden service automatically; no Tor install required. |
+
+Perfect for bots, CLIs, desktop apps, or embedding in Flutter.
+
+---
+
+## 🚀 Features
+
+* **Multi-platform** – runs anywhere Dart VM runs ✔  
+* **Automatic Tor/Arti** – `dart run whisper_node:tor` launches a hidden service for you ✔  
+* **gRPC over onion** – multiplexed, binary, schema-safe ✔  
+* **Envelope store-and-forward** – offline delivery with spam-PoW ✔  
+* **Group chat** – federated membership & signed admin events ✔  
+* **Identity graph** – user profiles + attestations ✔  
+* **Pluggable back-end** – swap LMDB ⇄ Hive ⇄ SQLite with one flag ✔  
+
+---
+
+## 📦 Installation
+
+```bash
+# 1. Install Dart ≥ 3.4
+# 2. Install TorChat globally
+dart pub global activate whisper_node
+# 3. Run a node
+whisper_node run
+```
+
+First launch will:
+
+1. Generate an Ed25519 keypair.  
+2. Start Arti & publish `xxxxxx.onion`.  
+3. Sync seed-peers and begin relaying.
+
+---
+
+## 🔧 Configuration
+
+`whisper_node.yaml` (auto-created in `$HOME/.whisper_node/`):
+
+```yaml
+listen_port: 20900
+data_dir: ~/.whisper_node/data
+tor:
+  enabled: true
+  socks_port: 9050          # 0 = random
+storage:
+  backend: hive             # hive | sqlite | lmdb
+pow:
+  difficulty: 20            # leading zero bits
+```
+
+Change, save, restart — settings hot-reload.
+
+---
+
+## 📚 gRPC & Protobuf Docs
+
+- **Protos** live in [`/proto`](proto/) and are versioned in this repo.  
+- `make protodocs` autogenerates HTML docs for every RPC & message.  
+- Language stubs: `dart run build_runner` (Dart) or `buf generate` (all major languages).
+
+### Quick test with `grpcurl`
+
+```bash
+grpcurl -plaintext -protoset out/descriptor.pb \
+  -d '{"value":"<your pubkey hex>"}' \
+  127.0.0.1:20900 torchat.Relay/GetEnvelopes
+```
+
+---
+
+## 🛠️ Dart SDK snippet
+
+```dart
+import 'package:whisper_node/whisper.dart';
+
+void main() async {
+  final node = await TorChat.bootstrap();       // starts Tor + gRPC
+  final client = node.client;
+
+  await client.sendMessage(
+    recipientPk: '<hex>',
+    text: 'Hello, dark net!',
+  );
+
+  client.onMessage.listen((msg) {
+    print('${msg.senderShort}: ${msg.text}');
+  });
+}
+```
+
+---
+
+## 🗺 Roadmap
+
+| Phase | Goal | ETA |
+|-------|------|-----|
+| **v0.1** | MVP relay + direct messages | ✅ now |
+| **v0.2** | Group chats + signed admin events | Jun 2025 |
+| **v0.3** | Mobile Flutter wrapper | Q3 2025 |
+| **v1.0** | Plugin marketplace, file transfer, sticker packs | Q1 2026 |
+
+---
+
+## 🤝 Contributing
+
+1. `git clone https://foss.haveno.com/haveno-network/whisper_node_dart`
+2. `dart pub get`
+3. `dart test`
+4. PRs welcome — keep commits sign-off (`-s`) for DCO.
+
+---
+
+## 🛡 License
+
+AGPL-3.0-or-later — code wants to stay free.
+
+> _“They can block the site, they can censor the net — but they can’t stop the whisper.”_
+
+---
\ No newline at end of file