swarm neighbours

1 files changed, 7 insertions, 2 deletions

diff --git a/docs/peers.md b/docs/peers.md
index 29512a5..2ff10e0 100644
--- a/docs/peers.md
+++ b/docs/peers.md
@@ -278,8 +278,13 @@ neighbours are its neighbours on each transport it is on: every transport's grap
 connected, and a member on two transports is in both, so as long as some members are
 on several, the swarm is connected, and those have about `k` neighbours per
 transport. With 100 members of which 10 are online,
-the 10 form a full mesh; nodes that briefly disagree on who is reachable only add links. `k` is `--neighbours` (default 12), so swarms of up to 13 nodes are a
-full mesh. A node *initiates* only towards its neighbours (HELLO, keepalive, dormancy
+the 10 form a full mesh; nodes that briefly disagree on who is reachable only add links. `k` is the swarm's: its genesis node records its
+`--neighbours` (default 12) in the document (`_continuum/neighbours`), and every node
+builds the graph with that value, since every node must build the same one (the
+writers' trees are built on it); a protocol writer may change it later, and every node
+then recomputes its neighbours and the trees. A swarm from before it was recorded has
+none, and each node uses its own `--neighbours`, which must then be the same
+everywhere. So swarms of up to `k` + 1 nodes (13 by default) are a full mesh. A node *initiates* only towards its neighbours (HELLO, keepalive, dormancy
 checks, sync openings, pushing its changes, epoch announcements, the heal, the peer list
 in HELLO_REPLY) and *answers* anyone. Changes travel over several hops; heads in
 keepalives tell a node when a neighbour has something it lacks. Until a node is ready