Updates

MODULE_CATEGORIES.md

@@ -1,6 +1,6 @@
 # Module categories (v2)
 
-152 modules in **30** category directories. Tiers: **production** (52) · **scaffold** (100).
+152 modules in **29** category directories. All **production**.
 
 Source of truth: [`MODULE_REGISTRY.yaml`](MODULE_REGISTRY.yaml).
 
@@ -51,27 +51,24 @@ Source of truth: [`MODULE_REGISTRY.yaml`](MODULE_REGISTRY.yaml).
 - 🟢 **hyper-p2p-schema-validator** — `schema-validator/v1` (production)
 - 🟢 **hyper-p2p-wire-registry** — `wire-registry/v1` (production)
 
-## Experimental (Wave 4) (`experimental`) — 10 modules
+## Experimental (`experimental`) — 16 modules
 
 - 🟢 **hyper-p2p-contradiction-graph** — `contradiction-graph/v1` (production)
 - 🟢 **hyper-p2p-entropy-beacon** — `entropy-beacon/v1` (production)
+- 🟢 **hyper-p2p-entropy-spiral** — `entropy-spiral/v1` (production)
 - 🟢 **hyper-p2p-gravity-well** — `gravity-well/v1` (production)
+- 🟢 **hyper-p2p-memetic-spread** — `memetic-spread/v1` (production)
 - 🟢 **hyper-p2p-mirror-realm** — `mirror-realm/v1` (production)
 - 🟢 **hyper-p2p-mycelium-pool** — `mycelium-pool/v1` (production)
 - 🟢 **hyper-p2p-paradox-clock** — `paradox-clock/v1` (production)
-- 🟢 **hyper-p2p-pheromone-trail** — `pheromone-trail/v1` (production)
-- 🟢 **hyper-p2p-silence-protocol** — `silence-protocol/v1` (production)
-- 🟢 **hyper-p2p-time-capsule** — `time-capsule/v1` (production)
-- 🟢 **hyper-p2p-whisper-mesh** — `whisper-mesh/v1` (production)
-
-## Experimental (Wave 5) (`experimental-wave5`) — 6 modules
-
-- 🟢 **hyper-p2p-entropy-spiral** — `entropy-spiral/v1` (production)
-- 🟢 **hyper-p2p-memetic-spread** — `memetic-spread/v1` (production)
 - 🟢 **hyper-p2p-paradox-merge** — `paradox-merge/v1` (production)
 - 🟢 **hyper-p2p-phase-shift-clock** — `phase-shift-clock/v1` (production)
+- 🟢 **hyper-p2p-pheromone-trail** — `pheromone-trail/v1` (production)
+- 🟢 **hyper-p2p-silence-protocol** — `silence-protocol/v1` (production)
 - 🟢 **hyper-p2p-tension-field** — `tension-field/v1` (production)
+- 🟢 **hyper-p2p-time-capsule** — `time-capsule/v1` (production)
 - 🟢 **hyper-p2p-void-channel** — `void-channel/v1` (production)
+- 🟢 **hyper-p2p-whisper-mesh** — `whisper-mesh/v1` (production)
 
 ## Indexes & search (`indexes-search`) — 8 modules
 

MODULE_REGISTRY.yaml

@@ -15,7 +15,7 @@ categories: {
   "agents-workflows": "Agents & workflows",
   "indexes-search": "Indexes & search",
   "oracles": "Oracles",
-  "experimental": "Experimental (Wave 4)",
+  "experimental": "Experimental",
   "storage-hypercore": "Storage (Hypercore)",
   "storage-hyperbee": "Storage (Hyperbee)",
   "storage-hyperdrive": "Storage (Hyperdrive)",
@@ -29,8 +29,7 @@ categories: {
   "observability": "Observability",
   "pear-platform": "Pear / Bare platform",
   "applications-collab": "Applications (collaboration)",
-  "applications-economy": "Applications (economy)",
+  "applications-economy": "Applications (economy)"
-  "experimental-wave5": "Experimental (Wave 5)"
 }
 modules:
 - name: hyper-p2p-protocol-handshake
@@ -1488,7 +1487,7 @@ modules:
   - hyper-p2p-capabilities
   wave: 8
 - name: hyper-p2p-entropy-spiral
-  category: experimental-wave5
+  category: experimental
   tier: production
   status: implemented
   protocol: entropy-spiral/v1
@@ -1500,7 +1499,7 @@ modules:
   - hyper-p2p-gossip-mesh
   wave: 8
 - name: hyper-p2p-phase-shift-clock
-  category: experimental-wave5
+  category: experimental
   tier: production
   status: implemented
   protocol: phase-shift-clock/v1
@@ -1512,7 +1511,7 @@ modules:
   - hyper-p2p-vector-clock
   wave: 8
 - name: hyper-p2p-tension-field
-  category: experimental-wave5
+  category: experimental
   tier: production
   status: implemented
   protocol: tension-field/v1
@@ -1524,7 +1523,7 @@ modules:
   - hyper-p2p-gossip-mesh
   wave: 8
 - name: hyper-p2p-void-channel
-  category: experimental-wave5
+  category: experimental
   tier: production
   status: implemented
   protocol: void-channel/v1
@@ -1536,7 +1535,7 @@ modules:
   - hyper-p2p-whisper-mesh
   wave: 8
 - name: hyper-p2p-memetic-spread
-  category: experimental-wave5
+  category: experimental
   tier: production
   status: implemented
   protocol: memetic-spread/v1
@@ -1548,7 +1547,7 @@ modules:
   - hyper-p2p-gossip-mesh
   wave: 8
 - name: hyper-p2p-paradox-merge
-  category: experimental-wave5
+  category: experimental
   tier: production
   status: implemented
   protocol: paradox-merge/v1

README.md

@@ -53,8 +53,7 @@ Packages live under **30 functional categories** (one folder per category). Cate
 | Agents & workflows | 3 | Agent memory, task orchestrator, workflow graph |
 | Applications (collaboration) | 4 | Collab rooms, cursors, line locks, whiteboard ops |
 | Applications (economy) | 3 | Auctions, credit ledger, marketplace listings |
-| Experimental | 10 | Research primitives (entropy, trails, capsules, whispers, …) |
+| Experimental | 16 | Research primitives (entropy, trails, void channel, memetic spread, …) |
-| Experimental (extended) | 6 | Void channels, memetic spread, tension fields, phase clocks, … |
 | Pear / Bare platform | 4 | Bundles, distributables, Pear runtime session, update gossip |
 | Oracles | 1 | Decentralized oracle gossip |
 | Time & ordering | 1 | Temporal index |
@@ -83,7 +82,7 @@ Most networked apps compose layers rather than importing everything:
 
 Reference compositions live under `examples/` (network stack demo, full messaging/collab stack, encoding stack). See the examples index at the repository root.
 
-Topic guides for large categories (network stack, experimental) are under `docs/` at the repository root.
+Category guides under `docs/` at the repository root: network stack, experimental, messaging, storage-hyperdrive, applications-collab, observability (see `docs/README.md`).
 
 ## Working on one module
 

_shared/DOC_STANDARDS.md

@@ -1,6 +1,6 @@
 # Documentation standards (exhaustive)
 
-All **152** modules and hub docs follow these rules. Hub files that must stay in sync on doc passes: root [`README.md`](../../README.md), [`docs/network-stack/README.md`](../../docs/network-stack/README.md), [`modules/network-stack/README.md`](../network-stack/README.md), [`docs/experimental/README.md`](../../docs/experimental/README.md), [`modules/experimental/README.md`](../experimental/README.md), [`modules/experimental-wave5/README.md`](../experimental-wave5/README.md). Source of truth: `index.js` + [`p2p-bare.js`](p2p-bare.js).
+All **152** modules and hub docs follow these rules. Hub files that must stay in sync on doc passes: root [`README.md`](../../README.md), [`docs/network-stack/README.md`](../../docs/network-stack/README.md), [`modules/network-stack/README.md`](../network-stack/README.md), [`docs/experimental/README.md`](../../docs/experimental/README.md), [`modules/experimental/README.md`](../experimental/README.md). Source of truth: `index.js` + [`p2p-bare.js`](p2p-bare.js).
 
 Regenerate module docs:
 

applications-collab/README.md

@@ -1,10 +1,30 @@
 # Applications (collaboration)
 
-**Path:** `modules/applications-collab/` · **Modules:** 4 (4 production, 0 scaffold)
+**Modules:** 4 (production)
 
-See [MODULE_CATEGORIES.md](../MODULE_CATEGORIES.md#applications-collab).
+Real-time collaboration primitives: rooms, whiteboard ops, cursor presence, and per-line locks — all gossip-synced on a shared topic.
 
-- [hyper-p2p-collab-room](./hyper-p2p-collab-room/) — production
+Hub: [`../../docs/applications-collab/README.md`](../../docs/applications-collab/README.md)
-- [hyper-p2p-cursor-presence](./hyper-p2p-cursor-presence/) — production
+
-- [hyper-p2p-document-line-lock](./hyper-p2p-document-line-lock/) — production
+## Packages
-- [hyper-p2p-whiteboard-op](./hyper-p2p-whiteboard-op/) — production
+
+| Module | Protocol | Role |
+|--------|----------|------|
+| [hyper-p2p-collab-room](./hyper-p2p-collab-room/) | `collab-room/v1` | Rooms, members, broadcast log |
+| [hyper-p2p-whiteboard-op](./hyper-p2p-whiteboard-op/) | `whiteboard-op/v1` | Append-only op log per room |
+| [hyper-p2p-cursor-presence](./hyper-p2p-cursor-presence/) | `cursor-presence/v1` | Per-doc cursors |
+| [hyper-p2p-document-line-lock](./hyper-p2p-document-line-lock/) | `document-line-lock/v1` | Line-level locks |
+
+## Quick start
+
+```js
+const { HyperP2PCollabRoom } = require('hyper-p2p-collab-room')
+const room = new HyperP2PCollabRoom({ topic: 'editors' })
+await room.ready()
+room.createRoom('doc-1')
+room.join('doc-1')
+room.broadcast('doc-1', { type: 'ping' })
+await room.close()
+```
+
+Integration: `whiteboard-op-two-node.js`, `collab-room-two-node.js` under `real_tests/integration/`.

applications-collab/hyper-p2p-collab-room/README.md

@@ -1,6 +1,6 @@
 # hyper-p2p-collab-room
 
-Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
+Collaboration rooms — `createRoom`, `join`, `leave`, `broadcast` with member maps and gossiped events.
 
 **Category:** General
 

applications-collab/hyper-p2p-cursor-presence/README.md

@@ -1,6 +1,6 @@
 # hyper-p2p-cursor-presence
 
-Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
+Per-document cursor positions — `updateCursor`, `listCursors`, gossiped cursor/remove events.
 
 **Category:** General
 

applications-collab/hyper-p2p-document-line-lock/README.md

@@ -1,6 +1,6 @@
 # hyper-p2p-document-line-lock
 
-Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
+Line-level document locks — `acquire` / `release` with holder conflict detection over gossip.
 
 **Category:** General
 

applications-collab/hyper-p2p-whiteboard-op/README.md

@@ -1,6 +1,6 @@
 # hyper-p2p-whiteboard-op
 
-Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
+Append-only whiteboard op log per room — `apply` and `history` with `wb-op` gossip replication.
 
 **Category:** General
 

encoding-wire/README.md

@@ -1,10 +1,25 @@
 # Encoding & wire formats
 
-**Path:** `modules/encoding-wire/` · **Modules:** 4 (4 production, 0 scaffold)
+**Modules:** 4 (production)
 
-See [MODULE_CATEGORIES.md](../MODULE_CATEGORIES.md#encoding-wire).
+Payload envelopes, codec registry, schema validation, and compact-encoding bridge for consistent Protomux bytes.
 
-- [hyper-p2p-compact-codec-bridge](./hyper-p2p-compact-codec-bridge/) — production
+## Packages
-- [hyper-p2p-message-envelope](./hyper-p2p-message-envelope/) — production
+
-- [hyper-p2p-schema-validator](./hyper-p2p-schema-validator/) — production
+| Module | Protocol | Role |
-- [hyper-p2p-wire-registry](./hyper-p2p-wire-registry/) — production
+|--------|----------|------|
+| [hyper-p2p-message-envelope](./hyper-p2p-message-envelope/) | `message-envelope/v1` | Checksum envelopes |
+| [hyper-p2p-wire-registry](./hyper-p2p-wire-registry/) | `wire-registry/v1` | Codec + protocol registry |
+| [hyper-p2p-schema-validator](./hyper-p2p-schema-validator/) | `schema-validator/v1` | JSON schema checks |
+| [hyper-p2p-compact-codec-bridge](./hyper-p2p-compact-codec-bridge/) | `compact-codec-bridge/v1` | compact-encoding helpers |
+
+## Quick start
+
+```js
+const { HyperP2PMessageEnvelope } = require('hyper-p2p-message-envelope')
+const env = new HyperP2PMessageEnvelope()
+const wire = env.wrapAndEncode({ ok: true })
+console.log(env.decodeAndUnwrap(wire))
+```
+
+Demo: `examples/wave9-encoding-stack/`.

encoding-wire/hyper-p2p-message-envelope/README.md

@@ -1,6 +1,6 @@
 # hyper-p2p-message-envelope
 
-Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
+Versioned payloads with checksums — `wrap`, `unwrap`, `encode`, `decode` for Protomux bytes.
 
 **Category:** General
 

encoding-wire/hyper-p2p-wire-registry/README.md

@@ -1,6 +1,6 @@
 # hyper-p2p-wire-registry
 
-Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
+Registry of compact-encoding codecs and protocol ids — `registerCodec`, `encode`, `decode`.
 
 **Category:** General
 

experimental-wave5/README.md

@@ -1,54 +0,0 @@
-# Experimental (Wave 5)
-
-**Path:** `modules/experimental-wave5/` · **Modules:** 6 (all production, `0.3.x`)
-
-Second-wave experimental primitives: entropy spirals, memetic spread, paradox merge, phase clocks, tension fields, and void channels. Full hub: [`../../docs/experimental/README.md`](../../docs/experimental/README.md).
-
-See also [MODULE_CATEGORIES.md](../MODULE_CATEGORIES.md#experimental-wave-5-experimental-wave5--6-modules).
-
-## When to use
-
-Building on Wave 4 modules when you need void semantics, memetic infection models, or turn-based entropy coordination over gossip.
-
-## When not to use
-
-Core app logic that only needs topic channels, RPC, or CRDTs — prefer production categories in [`MODULE_CATEGORIES.md`](../MODULE_CATEGORIES.md).
-
-## Quick start
-
-```js
-const { HyperP2PVoidChannel } = require('hyper-p2p-void-channel')
-const v = new HyperP2PVoidChannel({ topic: 'void-demo' })
-await v.ready()
-v.subscribeVoid('alerts', (e) => console.log('void', e))
-v.publishVoid('alerts', { reason: 'reset' })
-await v.close()
-```
-
-```bash
-cd modules/experimental-wave5/hyper-p2p-void-channel && npm install && npm test
-```
-
-## Docs
-
-| Module | Protocol | Summary |
-|--------|----------|---------|
-| [hyper-p2p-entropy-spiral](./hyper-p2p-entropy-spiral/) | `entropy-spiral/v1` | Turn-gated entropy spiral |
-| [hyper-p2p-memetic-spread](./hyper-p2p-memetic-spread/) | `memetic-spread/v1` | Meme infection + strain |
-| [hyper-p2p-paradox-merge](./hyper-p2p-paradox-merge/) | `paradox-merge/v1` | Paradox merge lattice |
-| [hyper-p2p-phase-shift-clock](./hyper-p2p-phase-shift-clock/) | `phase-shift-clock/v1` | Phase-shift ordering |
-| [hyper-p2p-tension-field](./hyper-p2p-tension-field/) | `tension-field/v1` | Scalar tension field gossip |
-| [hyper-p2p-void-channel](./hyper-p2p-void-channel/) | `void-channel/v1` | Void publish / subscribe |
-
-Gold-standard docs example: [hyper-p2p-void-channel/docs/api.md](./hyper-p2p-void-channel/docs/api.md).
-
-## Test
-
-```bash
-for d in hyper-p2p-*/; do (cd "$d" && npm test) || exit 1; done
-../../real_tests/run-all.sh --tier=production
-```
-
-## Composition
-
-Pairs with Wave 4 [`whisper-mesh`](../experimental/hyper-p2p-whisper-mesh/) and [`topic-channel`](../messaging-pubsub/hyper-p2p-topic-channel/). Details: [`docs/experimental/README.md`](../../docs/experimental/README.md).

experimental/README.md

@@ -1,18 +1,16 @@
-# Experimental (Wave 4)
+# Experimental
 
-**Path:** `modules/experimental/` · **Modules:** 10 (all production, `0.3.x`)
+**Path:** `modules/experimental/` · **Modules:** 16 (production)
 
-Research-oriented P2P primitives: contradiction tracking, shared entropy, routing metaphors, time capsules, and whisper meshes. Full hub: [`../../docs/experimental/README.md`](../../docs/experimental/README.md).
+Research-oriented P2P primitives: contradiction graphs, entropy, routing metaphors, time capsules, whispers, void channels, memetic spread, and related coordination experiments. Hub: [`../../docs/experimental/README.md`](../../docs/experimental/README.md).
-
-See also [MODULE_CATEGORIES.md](../MODULE_CATEGORIES.md#experimental-wave-4-experimental--10-modules).
 
 ## When to use
 
-Multi-peer experiments on one Hyperswarm topic where you need a **named protocol** and domain gossip (not raw KV). Good for demos, papers, and composition with Wave 5 void/memetic modules.
+Multi-peer experiments on one Hyperswarm topic with **named protocols** and typed gossip (not raw KV). Suitable for demos, prototypes, and composition with messaging or network-stack modules.
 
 ## When not to use
 
-Stable production messaging or storage — use `messaging-pubsub`, `network-stack`, or `storage-*` categories instead.
+Stable production apps that only need topic channels, RPC, or storage — use `messaging-pubsub`, `network-stack`, or `storage-*` instead.
 
 ## Quick start
 
@@ -21,41 +19,49 @@ const { HyperP2PContradictionGraph } = require('hyper-p2p-contradiction-graph')
 const g = new HyperP2PContradictionGraph({ topic: 'my-exp-topic' })
 await g.ready()
 g.claim('node', 'color', 'blue')
-console.log(g.conflictSet())
 await g.close()
 ```
 
-```bash
+```js
-cd modules/experimental/hyper-p2p-contradiction-graph && npm install && npm test
+const { HyperP2PVoidChannel } = require('hyper-p2p-void-channel')
+const v = new HyperP2PVoidChannel({ topic: 'void-demo' })
+await v.ready()
+v.publishVoid('alerts', { reason: 'reset' })
+await v.close()
 ```
 
-## Docs
+## Modules
 
 | Module | Protocol | Summary |
 |--------|----------|---------|
 | [hyper-p2p-contradiction-graph](./hyper-p2p-contradiction-graph/) | `contradiction-graph/v1` | Claims + conflict detection |
 | [hyper-p2p-entropy-beacon](./hyper-p2p-entropy-beacon/) | `entropy-beacon/v1` | XOR entropy pool + `draw` |
+| [hyper-p2p-entropy-spiral](./hyper-p2p-entropy-spiral/) | `entropy-spiral/v1` | Turn-gated entropy spiral |
 | [hyper-p2p-gravity-well](./hyper-p2p-gravity-well/) | `gravity-well/v1` | Peer mass + message attraction |
+| [hyper-p2p-memetic-spread](./hyper-p2p-memetic-spread/) | `memetic-spread/v1` | Meme infection + strain |
 | [hyper-p2p-mirror-realm](./hyper-p2p-mirror-realm/) | `mirror-realm/v1` | Forkable realm KV + reconcile |
 | [hyper-p2p-mycelium-pool](./hyper-p2p-mycelium-pool/) | `mycelium-pool/v1` | Donate/borrow credit pool |
 | [hyper-p2p-paradox-clock](./hyper-p2p-paradox-clock/) | `paradox-clock/v1` | Paradox stamps + resolve |
+| [hyper-p2p-paradox-merge](./hyper-p2p-paradox-merge/) | `paradox-merge/v1` | Paradox merge lattice |
+| [hyper-p2p-phase-shift-clock](./hyper-p2p-phase-shift-clock/) | `phase-shift-clock/v1` | Phase-shift ordering |
 | [hyper-p2p-pheromone-trail](./hyper-p2p-pheromone-trail/) | `pheromone-trail/v1` | Trail deposit / sniff / routing |
 | [hyper-p2p-silence-protocol](./hyper-p2p-silence-protocol/) | `silence-protocol/v1` | Seen vs absent id sets |
+| [hyper-p2p-tension-field](./hyper-p2p-tension-field/) | `tension-field/v1` | Scalar tension field gossip |
 | [hyper-p2p-time-capsule](./hyper-p2p-time-capsule/) | `time-capsule/v1` | Seal / attest / timed open |
+| [hyper-p2p-void-channel](./hyper-p2p-void-channel/) | `void-channel/v1` | Void publish / subscribe |
 | [hyper-p2p-whisper-mesh](./hyper-p2p-whisper-mesh/) | `whisper-mesh/v1` | Ephemeral whispers |
 
-Each row links to `README.md`, `docs/api.md`, `docs/architecture.md`, and `examples/basic.js`.
+Reference docs: [hyper-p2p-void-channel](./hyper-p2p-void-channel/docs/api.md).
 
 ## Test
 
 ```bash
-# This category (run each or use full matrix)
+cd modules/experimental/hyper-p2p-void-channel && npm install && npm test
+# or all packages in this folder:
 for d in hyper-p2p-*/; do (cd "$d" && npm test) || exit 1; done
-
-# Full repo production tier (152 modules)
 ../../real_tests/run-all.sh --tier=production
 ```
 
 ## Composition
 
-Typical chains: `entropy-beacon` + `pheromone-trail` → `whisper-mesh` → Wave 5 `void-channel`. See [`docs/experimental/README.md`](../../docs/experimental/README.md#composition-graph-typical).
+Typical chain: `entropy-beacon` → `pheromone-trail` → `whisper-mesh` → `void-channel`. See [`docs/experimental/README.md`](../../docs/experimental/README.md).

experimental/hyper-p2p-entropy-spiral/docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture: hyper-p2p-entropy-spiral
 
-**Category:** `experimental-wave5` · **Protocol:** `entropy-spiral/v1`
+**Category:** `experimental` · **Protocol:** `entropy-spiral/v1`
 
 ## Role
 

experimental/hyper-p2p-memetic-spread/docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture: hyper-p2p-memetic-spread
 
-**Category:** `experimental-wave5` · **Protocol:** `memetic-spread/v1`
+**Category:** `experimental` · **Protocol:** `memetic-spread/v1`
 
 ## Wire messages
 

experimental/hyper-p2p-paradox-merge/docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture: hyper-p2p-paradox-merge
 
-**Category:** `experimental-wave5` · **Protocol:** `paradox-merge/v1`
+**Category:** `experimental` · **Protocol:** `paradox-merge/v1`
 
 ## Wire messages
 

experimental/hyper-p2p-phase-shift-clock/docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture: hyper-p2p-phase-shift-clock
 
-**Category:** `experimental-wave5` · **Protocol:** `phase-shift-clock/v1`
+**Category:** `experimental` · **Protocol:** `phase-shift-clock/v1`
 
 ## Wire messages
 

experimental/hyper-p2p-tension-field/docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture: hyper-p2p-tension-field
 
-**Category:** `experimental-wave5` · **Protocol:** `tension-field/v1`
+**Category:** `experimental` · **Protocol:** `tension-field/v1`
 
 ## Wire messages
 

experimental/hyper-p2p-void-channel/docs/api.md

@@ -62,7 +62,7 @@ Void messages are idempotent per channel (latest stored in `_voids`).
 ## Testing
 
 ```bash
-cd modules/experimental-wave5/hyper-p2p-void-channel && npm test
+cd modules/experimental/hyper-p2p-void-channel && npm test
 ```
 
 ## Composition

experimental/hyper-p2p-void-channel/docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture: hyper-p2p-void-channel
 
-**Protocol:** `void-channel/v1` · **Category:** experimental-wave5
+**Protocol:** `void-channel/v1` · **Category:** experimental
 
 ## Wire messages
 

messaging-pubsub/README.md

@@ -1,10 +1,27 @@
 # Messaging pub/sub
 
-**Path:** `modules/messaging-pubsub/` · **Modules:** 4 (4 production, 0 scaffold)
+**Modules:** 4 (production)
 
-See [MODULE_CATEGORIES.md](../MODULE_CATEGORIES.md#messaging-pubsub).
+Channel-based publish/subscribe on one Hyperswarm topic: named channels, handlers, optional retain, QoS, and subscription leases.
 
-- [hyper-p2p-qos-topic](./hyper-p2p-qos-topic/) — production
+## Packages
-- [hyper-p2p-retained-messages](./hyper-p2p-retained-messages/) — production
+
-- [hyper-p2p-subscription-lease](./hyper-p2p-subscription-lease/) — production
+| Module | Protocol | Role |
-- [hyper-p2p-topic-channel](./hyper-p2p-topic-channel/) — production
+|--------|----------|------|
+| [hyper-p2p-topic-channel](./hyper-p2p-topic-channel/) | `topic-channel/v1` | Core channel pub/sub + retain |
+| [hyper-p2p-qos-topic](./hyper-p2p-qos-topic/) | `qos-topic/v1` | Priority queues 0–2 |
+| [hyper-p2p-retained-messages](./hyper-p2p-retained-messages/) | `retained-messages/v1` | Standalone retain store |
+| [hyper-p2p-subscription-lease](./hyper-p2p-subscription-lease/) | `subscription-lease/v1` | Exclusive channel leases |
+
+## Quick start
+
+```js
+const { HyperP2PTopicChannel } = require('hyper-p2p-topic-channel')
+const ch = new HyperP2PTopicChannel({ topic: 'app' })
+await ch.ready()
+ch.subscribe('events', (m) => console.log(m.payload))
+ch.publish('events', { hello: true })
+await ch.close()
+```
+
+See [`../../docs/messaging/README.md`](../../docs/messaging/README.md).

messaging-pubsub/hyper-p2p-qos-topic/README.md

@@ -1,6 +1,6 @@
 # hyper-p2p-qos-topic
 
-Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
+Priority pub/sub with three QoS levels — subscribers declare minimum QoS; publishes drain highest priority first.
 
 **Category:** General
 

messaging-pubsub/hyper-p2p-retained-messages/README.md

@@ -1,6 +1,6 @@
 # hyper-p2p-retained-messages
 
-Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
+Local retained-message store per channel — ring buffer of last payloads for subscribe replay (pairs with topic-channel).
 
 **Category:** General
 

messaging-pubsub/hyper-p2p-subscription-lease/README.md

@@ -1,6 +1,6 @@
 # hyper-p2p-subscription-lease
 
-Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
+Time-bounded exclusive channel leases — `acquire`, `renew`, `release` with optional expiry sweeps.
 
 **Category:** General
 

messaging-pubsub/hyper-p2p-topic-channel/README.md

@@ -1,16 +1,16 @@
 # hyper-p2p-topic-channel
 
-Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
+Named channel pub/sub with optional retained last message — `subscribe`, `publish`, and `syncRetained` over one Hyperswarm topic.
 
-**Category:** General
+**Category:** Messaging pub/sub
 
-**Composes with:** 
+**Composes with:** `hyper-p2p-qos-topic`, `hyper-p2p-subscription-lease`, `hyper-p2p-retained-messages`
 
 **Protocol:** `topic-channel/v1`
 
 ## When to use
 
-Multi-peer apps that need general over a shared Hyperswarm topic.
+Apps that need MQTT-style channels, handler callbacks, and gossiped publish/subscribe on a shared topic.
 
 ## When not to use
 

messaging-streams/README.md

@@ -1,12 +1,28 @@
 # Messaging streams
 
-**Path:** `modules/messaging-streams/` · **Modules:** 6 (6 production, 0 scaffold)
+**Modules:** 6 (production)
 
-See [MODULE_CATEGORIES.md](../MODULE_CATEGORIES.md#messaging-streams).
+Local and composable byte-stream utilities: chunking, multiplexing, backpressure, tee, transform, and resume tokens. Wire framing is app-defined; pair with pub/sub or network transport.
 
-- [hyper-p2p-stream-backpressure](./hyper-p2p-stream-backpressure/) — production
+## Packages
-- [hyper-p2p-stream-chunker](./hyper-p2p-stream-chunker/) — production
+
-- [hyper-p2p-stream-multiplex](./hyper-p2p-stream-multiplex/) — production
+| Module | Protocol | Role |
-- [hyper-p2p-stream-resume-token](./hyper-p2p-stream-resume-token/) — production
+|--------|----------|------|
-- [hyper-p2p-stream-tee](./hyper-p2p-stream-tee/) — production
+| [hyper-p2p-stream-chunker](./hyper-p2p-stream-chunker/) | `stream-chunker/v1` | Fixed-size chunks |
-- [hyper-p2p-stream-transform](./hyper-p2p-stream-transform/) — production
+| [hyper-p2p-stream-multiplex](./hyper-p2p-stream-multiplex/) | `stream-multiplex/v1` | Many streams, one frame bus |
+| [hyper-p2p-stream-backpressure](./hyper-p2p-stream-backpressure/) | `stream-backpressure/v1` | High-water-mark buffer |
+| [hyper-p2p-stream-tee](./hyper-p2p-stream-tee/) | `stream-tee/v1` | Fan-out branches |
+| [hyper-p2p-stream-transform](./hyper-p2p-stream-transform/) | `stream-transform/v1` | Map/filter stage |
+| [hyper-p2p-stream-resume-token](./hyper-p2p-stream-resume-token/) | `stream-resume-token/v1` | Checkpoint replay |
+
+## Quick start
+
+```js
+const { HyperP2PStreamChunker } = require('hyper-p2p-stream-chunker')
+const c = new HyperP2PStreamChunker({ chunkSize: 4096 })
+c.on('chunk', (buf) => console.log(buf.length))
+c.push('hello world'.repeat(100))
+c.flush()
+```
+
+See [`../../docs/messaging/README.md`](../../docs/messaging/README.md).

messaging-streams/hyper-p2p-stream-backpressure/README.md

@@ -1,6 +1,6 @@
 # hyper-p2p-stream-backpressure
 
-Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
+Buffered stream with high-water-mark backpressure — `write` returns false when paused or over limit.
 
 **Category:** General
 

messaging-streams/hyper-p2p-stream-chunker/README.md

@@ -1,6 +1,6 @@
 # hyper-p2p-stream-chunker
 
-Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
+Fixed-size byte chunker — buffer `push`/`flush` for stream pipelines (local transform, no swarm).
 
 **Category:** General
 

messaging-streams/hyper-p2p-stream-multiplex/README.md

@@ -1,6 +1,6 @@
 # hyper-p2p-stream-multiplex
 
-Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
+Local stream multiplexing — `openStream`, framed `write`/`end`, and `receiveFrame` for many logical streams.
 
 **Category:** General
 

messaging-streams/hyper-p2p-stream-resume-token/README.md

@@ -1,6 +1,6 @@
 # hyper-p2p-stream-resume-token
 
-Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
+Stream checkpoints — `checkpoint` byte offsets and `readFromOffset` replay after resume.
 
 **Category:** General
 

messaging-streams/hyper-p2p-stream-tee/README.md

@@ -1,6 +1,6 @@
 # hyper-p2p-stream-tee
 
-Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
+Fan-out stream tee — `addBranch`, `write`, and per-branch `readBranch` queues (local).
 
 **Category:** General
 

messaging-streams/hyper-p2p-stream-tee/docs/api.md

@@ -73,6 +73,10 @@ Branches share buffer references; treat as trusted in-process only.
 5. Use `pending(name)` to detect backlog before applying backpressure upstream.
 6. Monitor `getStats().written` vs branch `pending` for imbalance.
 
+## Changelog
+
+- Initial production release with branch fan-out and per-branch FIFO queues.
+
 ## See also
 
 [`docs/architecture.md`](architecture.md)

messaging-streams/hyper-p2p-stream-transform/README.md

@@ -1,6 +1,6 @@
 # hyper-p2p-stream-transform
 
-Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
+Transform stream stage — optional `transform(buf)` on each `write` with output queue.
 
 **Category:** General
 

module-paths.json

@@ -66,7 +66,7 @@
   "hyper-p2p-drive-watch-notify": "storage-hyperdrive/hyper-p2p-drive-watch-notify",
   "hyper-p2p-encrypted-topic": "trust-security/hyper-p2p-encrypted-topic",
   "hyper-p2p-entropy-beacon": "experimental/hyper-p2p-entropy-beacon",
-  "hyper-p2p-entropy-spiral": "experimental-wave5/hyper-p2p-entropy-spiral",
+  "hyper-p2p-entropy-spiral": "experimental/hyper-p2p-entropy-spiral",
   "hyper-p2p-flow-shaper": "network-stack/hyper-p2p-flow-shaper",
   "hyper-p2p-fulltext-lite": "indexes-search/hyper-p2p-fulltext-lite",
   "hyper-p2p-geo-hint-router": "routing-advanced/hyper-p2p-geo-hint-router",
@@ -83,7 +83,7 @@
   "hyper-p2p-load-spread": "routing-advanced/hyper-p2p-load-spread",
   "hyper-p2p-log-gossip": "observability/hyper-p2p-log-gossip",
   "hyper-p2p-marketplace-listing": "applications-economy/hyper-p2p-marketplace-listing",
-  "hyper-p2p-memetic-spread": "experimental-wave5/hyper-p2p-memetic-spread",
+  "hyper-p2p-memetic-spread": "experimental/hyper-p2p-memetic-spread",
   "hyper-p2p-merge-registry": "routing-paths/hyper-p2p-merge-registry",
   "hyper-p2p-message-envelope": "encoding-wire/hyper-p2p-message-envelope",
   "hyper-p2p-metrics-aggregator": "observability/hyper-p2p-metrics-aggregator",
@@ -94,12 +94,12 @@
   "hyper-p2p-noise-session-wrap": "network-transport/hyper-p2p-noise-session-wrap",
   "hyper-p2p-overlay-topology": "network-stack/hyper-p2p-overlay-topology",
   "hyper-p2p-paradox-clock": "experimental/hyper-p2p-paradox-clock",
-  "hyper-p2p-paradox-merge": "experimental-wave5/hyper-p2p-paradox-merge",
+  "hyper-p2p-paradox-merge": "experimental/hyper-p2p-paradox-merge",
   "hyper-p2p-pattern-router": "routing-paths/hyper-p2p-pattern-router",
   "hyper-p2p-peer-bootstrap-store": "network-discovery/hyper-p2p-peer-bootstrap-store",
   "hyper-p2p-peer-scheduler": "scheduling-queues/hyper-p2p-peer-scheduler",
   "hyper-p2p-percentile-sketch": "measurement-rate-control/hyper-p2p-percentile-sketch",
-  "hyper-p2p-phase-shift-clock": "experimental-wave5/hyper-p2p-phase-shift-clock",
+  "hyper-p2p-phase-shift-clock": "experimental/hyper-p2p-phase-shift-clock",
   "hyper-p2p-pheromone-trail": "experimental/hyper-p2p-pheromone-trail",
   "hyper-p2p-presence": "core-infrastructure/hyper-p2p-presence",
   "hyper-p2p-protocol-handshake": "network-stack/hyper-p2p-protocol-handshake",
@@ -132,7 +132,7 @@
   "hyper-p2p-subscription-lease": "messaging-pubsub/hyper-p2p-subscription-lease",
   "hyper-p2p-task-orchestrator": "agents-workflows/hyper-p2p-task-orchestrator",
   "hyper-p2p-temporal-index": "time-ordering/hyper-p2p-temporal-index",
-  "hyper-p2p-tension-field": "experimental-wave5/hyper-p2p-tension-field",
+  "hyper-p2p-tension-field": "experimental/hyper-p2p-tension-field",
   "hyper-p2p-time-capsule": "experimental/hyper-p2p-time-capsule",
   "hyper-p2p-topic-announcer": "network-discovery/hyper-p2p-topic-announcer",
   "hyper-p2p-topic-channel": "messaging-pubsub/hyper-p2p-topic-channel",
@@ -142,7 +142,7 @@
   "hyper-p2p-trust-graph": "trust-security/hyper-p2p-trust-graph",
   "hyper-p2p-udx-metrics": "network-transport/hyper-p2p-udx-metrics",
   "hyper-p2p-vector-clock": "core-infrastructure/hyper-p2p-vector-clock",
-  "hyper-p2p-void-channel": "experimental-wave5/hyper-p2p-void-channel",
+  "hyper-p2p-void-channel": "experimental/hyper-p2p-void-channel",
   "hyper-p2p-wakeup-channel": "network-transport/hyper-p2p-wakeup-channel",
   "hyper-p2p-whisper-mesh": "experimental/hyper-p2p-whisper-mesh",
   "hyper-p2p-whiteboard-op": "applications-collab/hyper-p2p-whiteboard-op",

observability/README.md

@@ -1,11 +1,30 @@
 # Observability
 
-**Path:** `modules/observability/` · **Modules:** 5 (5 production, 0 scaffold)
+**Modules:** 5 (production)
 
-See [MODULE_CATEGORIES.md](../MODULE_CATEGORIES.md#observability).
+Traces, metrics, logs, health reports, and local stats aggregation — observability gossip for distributed signals, plus a local-only exporter registry.
 
-- [hyper-p2p-health-probe](./hyper-p2p-health-probe/) — production
+Hub: [`../../docs/observability/README.md`](../../docs/observability/README.md)
-- [hyper-p2p-log-gossip](./hyper-p2p-log-gossip/) — production
+
-- [hyper-p2p-metrics-aggregator](./hyper-p2p-metrics-aggregator/) — production
+## Packages
-- [hyper-p2p-stats-exporter](./hyper-p2p-stats-exporter/) — production
+
-- [hyper-p2p-trace-span](./hyper-p2p-trace-span/) — production
+| Module | Protocol | Role |
+|--------|----------|------|
+| [hyper-p2p-trace-span](./hyper-p2p-trace-span/) | `trace-span/v1` | Span start/end |
+| [hyper-p2p-metrics-aggregator](./hyper-p2p-metrics-aggregator/) | `metrics-aggregator/v1` | Numeric samples |
+| [hyper-p2p-log-gossip](./hyper-p2p-log-gossip/) | `log-gossip/v1` | Level-filtered logs |
+| [hyper-p2p-health-probe](./hyper-p2p-health-probe/) | `health-probe/v1` | Peer health reports |
+| [hyper-p2p-stats-exporter](./hyper-p2p-stats-exporter/) | `stats-exporter/v1` | Local snapshot registry |
+
+## Quick start
+
+```js
+const { HyperP2PTraceSpan } = require('hyper-p2p-trace-span')
+const tr = new HyperP2PTraceSpan({ topic: 'ops' })
+await tr.ready()
+const id = tr.startSpan('request')
+tr.endSpan(id)
+await tr.close()
+```
+
+Shared transport: [`../_shared/observability-base.js`](../_shared/observability-base.js).

observability/hyper-p2p-metrics-aggregator/README.md

@@ -1,6 +1,6 @@
 # hyper-p2p-metrics-aggregator
 
-Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
+Gossiped metric time series — `record`, `summarize`, rolling windows per label set.
 
 **Category:** General
 

observability/hyper-p2p-stats-exporter/README.md

@@ -1,6 +1,6 @@
 # hyper-p2p-stats-exporter
 
-Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
+Aggregate `getStats()` callbacks from multiple modules into one snapshot (local registry).
 
 **Category:** General
 

observability/hyper-p2p-trace-span/README.md

@@ -1,6 +1,6 @@
 # hyper-p2p-trace-span
 
-Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
+Distributed trace spans — `startSpan`, `endSpan`, parent links, observability gossip transport.
 
 **Category:** General