diff --git a/src/pg.rs b/src/pg.rs
index 29ab8bb..7eada12 100644
--- a/src/pg.rs
+++ b/src/pg.rs
@@ -6,6 +6,41 @@
 //! generalization of the bimap; it is its own keyspace sharing only the
 //! liveness signal source (monitors) and the lock *class*.
 //!
+//! ## Example
+//!
+//! A group is a live membership view: members join, and a member that dies is
+//! evicted automatically — no deregistration call, no bookkeeping.
+//!
+//! ```
+//! use smarm::{channel, join, leave, members, pick, run, spawn};
+//!
+//! run(|| {
+//!     let (tx1, rx1) = channel::<()>();
+//!     let (tx2, rx2) = channel::<()>();
+//!     let w1 = spawn(move || { rx1.recv().unwrap(); });
+//!     let w2 = spawn(move || { rx2.recv().unwrap(); });
+//!
+//!     // Workers join the group; `members` is the live view of it.
+//!     join("pool", w1.pid());
+//!     join("pool", w2.pid());
+//!     assert_eq!(members("pool").len(), 2);
+//!
+//!     // One worker dies. Nobody told the group — the death hook evicts it,
+//!     // so it is gone from `members` and never returned by `pick`.
+//!     tx1.send(()).unwrap();
+//!     w1.join().unwrap();
+//!     assert_eq!(members("pool"), vec![w2.pid()]);
+//!     assert_eq!(pick("pool"), Some(w2.pid()));
+//!
+//!     // Voluntary departure works too.
+//!     leave("pool", w2.pid());
+//!     assert!(pick("pool").is_none());
+//!
+//!     tx2.send(()).unwrap();
+//!     w2.join().unwrap();
+//! });
+//! ```
+//!
 //! ## Cleanup is eager and monitor-driven (unlike the registry)
 //!
 //! The registry prunes a stale binding lazily, on contact, because it only