Updates

measurement-rate-control/hyper-p2p-histogram-gossip/README.md

@@ -1,28 +1,37 @@
 # hyper-p2p-histogram-gossip
 
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `histogram-gossip/v1` · **Wave:** 8
+Per-metric histograms with bucket gossip merge over Hyperswarm.
 
-Histogram gossip.
+**Category:** measurement-rate-control
 
-## Holepunch references (inspiration only)
+**Protocol:** `histogram-gossip/v1`
 
-- `hyper-p2p-link-probe`
+## When to use
 
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+Aggregating latency or resource samples across peers for approximate percentiles.
 
-## Composes with
+## When not to use
 
-- `hyper-p2p-gossip-mesh`
+Exact global percentiles requiring centralized storage (use hyper-p2p-percentile-sketch locally).
 
-## Planned API
+## Quick start
 
-- `constructor(opts)` — topic, optional keyPair
-- `getStats()` — scaffold counters
-- `ready()` — no-op until implemented
-- Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
+```js
+const { HyperP2PHistogramGossip } = require('hyper-p2p-histogram-gossip')
+const m = new HyperP2PHistogramGossip({ topic: process.argv[2] })
+await m.ready()
+m.observe('latency', 42)
+console.log(m.percentile('latency', 95))
+await m.close()
+```
 
-## Layout
+## Docs
 
-`modules/measurement-rate-control/hyper-p2p-histogram-gossip/`
+- [docs/api.md](docs/api.md)
+- [docs/architecture.md](docs/architecture.md)
 
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+## Test
+
+```bash
+npm install && npm test
+```