From fd6c1b4f05090bc535f4a530ad85cfbcc4d38d92 Mon Sep 17 00:00:00 2001
From: "Maciek \"mab122\" Bator" <maciek+git@mbator.pl>
Date: Fri, 24 Apr 2026 11:36:18 +0200
Subject: [PATCH] docs: add Reticulum connectivity step to quickstart

Add step 1 covering Reticulum setup: LAN works automatically, for
other transports generate the example config with rnsd --exampleconfig
and configure the appropriate interface. Fixes missing instructions
that caused bridges not to discover each other on fresh installs.
Standardise on uv throughout.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 35 ++++++++++++++++++++---------------
 1 file changed, 20 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 949bb2f..4617680 100644
--- a/README.md
+++ b/README.md
@@ -8,11 +8,8 @@ Bridges [Radicle](https://radicle.xyz) (decentralized Git) over [Reticulum](http
 
 ## Prerequisites
 
-Install anything you don't already have:
-
 - **Radicle** — `rad` CLI + `radicle-node`: [radicle.xyz/install](https://radicle.xyz/install)
-- **Reticulum** — `rns` Python package: `pip install rns` or [reticulum.network](https://reticulum.network/manual/gettingstartedfast.html)
-- **Python 3.10+**
+- **uv**: [docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/) (manages Python and dependencies)
 
 ---
 
@@ -21,26 +18,34 @@ Install anything you don't already have:
 ```sh
 git clone rad:z4NMdcKbw2TETQ56fbQfbibFHtZqZ
 cd radicle-reticulum
-pip install .
-```
-
-With [uv](https://docs.astral.sh/uv/getting-started/installation/) instead of pip:
-
-```sh
 uv sync
 ```
 
 Optional — faster push detection on Linux/macOS (inotify):
 
 ```sh
-pip install ".[watch]"   # or: uv sync --extra watch
+uv sync --extra watch
 ```
 
 ---
 
 ## Quick start
 
-### 1. Tell radicle-node to listen on localhost
+Do this on **every machine**.
+
+### 1. Reticulum connectivity
+
+On the same LAN, Reticulum discovers peers automatically via multicast — no configuration needed.
+
+For other transports (internet, LoRa, packet radio, I2P) configure the appropriate Reticulum interface in `~/.reticulum/config` first. If this is your first time using Reticulum, generate the annotated example config:
+
+```sh
+rnsd --exampleconfig > ~/.reticulum/config
+```
+
+Then edit it to enable the interface for your transport. See [Reticulum interfaces](#reticulum-interfaces) below and the [Reticulum manual](https://reticulum.network/manual/) for details. Once Reticulum can reach between your machines the bridge works the same regardless of transport.
+
+### 2. Configure radicle-node to listen on localhost
 
 Edit `~/.radicle/config.json`:
 
@@ -57,7 +62,7 @@ rad node start
 rad node status   # should show "listening … 127.0.0.1:8776"
 ```
 
-### 2. Start the bridge on both machines
+### 3. Start the bridge on both machines
 
 ```sh
 uv run radicle-rns bridge
@@ -76,7 +81,7 @@ Tunnel 1 opened
 [Status] Tunnels: 1, Remote bridges: 1, TX: 1551, RX: 1831
 ```
 
-### 3. Use radicle normally
+### 4. Use radicle normally
 
 ```sh
 # Machine A
@@ -93,7 +98,7 @@ That's it. `rad push`, `rad fetch`, and `rad sync` all work as usual — they ta
 
 ## Reticulum interfaces
 
-On a LAN, Reticulum auto-discovers peers via UDP multicast — no config needed. For LoRa, serial, or I2P, edit `~/.reticulum/config`:
+For LoRa, serial, or I2P, edit `~/.reticulum/config`:
 
 ```ini
 [[lora_interface]]