improve gossip & protocols info

Author: okdistribute

concepts/protocols.mdx

@@ -2,4 +2,32 @@
 title: "Protocols"
 ---
 
-Placeholder: Overview of supported protocols and how to choose/design one.
+Assuming we have two endpoints connected, yay! Now we just have to… do something… with that connection. That’s where protocols come in.
+
+## Introduction
+
+A protocol sets up everything we need to both provide data we have locally when
+others request it, and ask other endpoints that run the protocol to do whatever
+business or application logic we need.
+
+Coming from the world of HTTP client/server models, protocols are similar to 
+request handlers. However, they go beyond request/response by creating multiple
+streams of data and usually include both initiating & accepting protocol
+connections in the same client.
+
+Peer to peer protocols do not require a client/server distinction, both sides
+can initiate and accept connections. However, you can still build client/server
+style protocols on top of iroh if you want to.
+
+Protocols are modules you compose together to add functionality to connections.
+Protocols exist for file transfer, game server sync, message broadcasting,
+document collaboration, all kinds of stuff. You can use off-the-shelf protocols
+to quickly add functionality, work directly with QUIC streams & build a fully
+custom protocol that does exactly what you want, or fork an existing protocol to
+get what you need.
+
+## Learn more
+- [iroh-gossip](/connecting/gossip): creating swarms of peers for broadcasting messages on topics.
+- [iroh-blobs](/protocols/blobs): storing and transferring large binary blobs of data.
+- [iroh-docs](/protocols/docs): collaborative key-value store. 
+- [Writing Custom Protocols](/protocols/writing-a-protocol): guide on building your own protocols on top of iroh.

connecting/gossip.mdx

@@ -16,18 +16,6 @@ Characteristics
 - Gossip spreads information redundantly across overlapping paths, which
 	improves resilience but increases traffic.
 
-How gossip compares to centralized systems
-- Central brokers (Kafka, MQTT, Pulsar) keep authoritative topic membership
-	and provide stronger delivery guarantees, but introduce a single point of
-	failure and operational overhead.
-- Gossip trades strict guarantees for decentralization, simplicity, and
-	resilience in highly dynamic environments.
-
-When to use gossip
-- Lightweight broadcast where eventual delivery is acceptable.
-- Dynamic membership (peers frequently join/leave or change addresses).
-- No single point of failure is desired.
-
 
 ## iroh-gossip
 
@@ -37,11 +25,18 @@ based on the papers
 [HyParView](https://asc.di.fct.unl.pt/~jleitao/pdf/dsn07-leitao.pdf) and
 [PlumTree](https://asc.di.fct.unl.pt/~jleitao/pdf/srds07-leitao.pdf).
 
+### Installation
+```
+cargo add iroh-gossip
+```
+
 Iroh provides a Router that takes an Endpoint and any protocols needed for the
 application. Similar to a router in webserver library, it runs a loop accepting
 incoming connections and routes them to the specific protocol handler, based on
 ALPN.
 
+### Example
+
 ```rust
 use iroh::{protocol::Router, Endpoint, EndpointId};
 use iroh_gossip::{api::Event, Gossip, TopicId};
@@ -145,3 +140,17 @@ joined the topic:
 receiver.joined().await?;
 ```
 
+
+## How gossip compares to centralized systems
+
+- Central brokers (Kafka, MQTT, Pulsar) keep authoritative topic membership
+	and provide stronger delivery guarantees, but introduce a single point of
+	failure and operational overhead.
+- Gossip trades strict guarantees for decentralization, simplicity, and
+	resilience in highly dynamic environments.
+
+## When to use gossip
+
+- Lightweight broadcast where eventual delivery is acceptable.
+- Dynamic membership (peers frequently join/leave or change addresses).
+- No single point of failure is desired.