Updates

2026-05-20 22:30:53 -04:00
parent e4400872c0
commit b8c335adee
89 changed files with 2862 additions and 765 deletions
@@ -3,3 +3,7 @@
 ## [0.0.0-scaffold] — Wave 8
 - Registry scaffold: file tree, load smoke tests, docs stubs
 ## [0.3.2] - 2026-05-21
 ### Changed
 - Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
@@ -1,28 +1,43 @@
 # hyper-p2p-collab-room
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `collab-room/v1` · **Wave:** 8
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-Collaboration room primitive.
+**Category:** General
-## Holepunch references (inspiration only)
+**Composes with:** 
- `hyperconf`
+**Protocol:** `collab-room/v1`
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+## When to use
-## Composes with
+Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-presence`
+## When not to use
-## Planned API
+Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair
+## Quick start
 - `getStats()` — scaffold counters
 - `ready()` — no-op until implemented
 - Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
-## Layout
+```js
 const { HyperP2PCollabRoom } = require('hyper-p2p-collab-room')
 const topic = process.argv[2] // 64-char hex or string
 const mod = new HyperP2PCollabRoom({ topic, enableBackgroundTimers: false })
 await mod.ready()   // joins swarm when topic set
 // ... application logic ...
 await mod.close()
 ```
-`modules/applications-collab/hyper-p2p-collab-room/`
+## Docs
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+- [docs/api.md](docs/api.md) — constructor, methods, events, errors
 - [docs/architecture.md](docs/architecture.md) — wire types, state, composition
 - [../../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
 - [../../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
 - Integration: [`../../real_tests/integration/`](../../real_tests/integration/) — `collab-room-two-node.js`
 ## Test
 ```bash
 npm install && npm test
 ```
@@ -1,23 +1,102 @@
-# hyper-p2p-collab-room API
+# API: hyper-p2p-collab-room
-**Status:** scaffold · **Protocol:** `collab-room/v1`
+**Protocol:** `collab-room/v1`
-## Class `HyperP2PCollabRoom`
+**Export:** `HyperP2PCollabRoom`
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+## Overview
-### `constructor(opts?)`
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-### `getStats()`
+## Constructor
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+```js
 const mod = new HyperP2PCollabRoom(opts)
 ```
-### `ready()`
+| Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `topic` | varies | null | topic |
 | `keyPair` | KeyPair | random Ed25519 | keyPair |
-Resolves immediately (no-op).
+## Methods
-## Wire (planned)
+### `createRoom(roomId, meta = {})`
-| Message | Direction | Notes |
+- **Returns:** `value`
-|---------|-----------|-------|
+- **Throws:** — (none documented in method body)
-| TBD | gossip | Defined in implementation pass |
+
 ### `join(roomId, meta = {})`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `leave(roomId)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `broadcast(roomId, event)`
 - **Returns:** `value`
 - **Throws:**
  - `Error: event object required`
  - `Error: room not found`
 ### `getMembers(roomId)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getEvents(roomId, limit = 50)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getStats(—)`
 - **Returns:** `object`
 - **Throws:** — (none documented in method body)
 ### `ready(—)`
 - **Returns:** `Promise`
 - **Throws:** — (none documented in method body)
 ### `close(—)`
 - **Returns:** `Promise<void>`
 - **Throws:** — (none documented in method body)
 ## Events
 | Event | Payload |
 |-------|---------|
 | `broadcast` | roomId, event, remote |
 | `closed` | no payload |
 | `join` | payload object |
 | `leave` | peer |
 | `peer-joined` | roomId, member |
 | `peer-left` | roomId, peer |
 | `room-created` | payload object |
 ## getStats()
 Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
 Library-only modules may include `mode: 'local'`.
 ## Errors
 Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 ## P2P
 When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `collab-room/v1`.
 ## Testing
 ```bash
 npm install && npm test
 ```
 Integration: [`../../../real_tests/integration/collab-room-two-node.js`](../../../real_tests/integration/collab-room-two-node.js)
@@ -1,15 +1,45 @@
-# hyper-p2p-collab-room architecture
+# Architecture: hyper-p2p-collab-room
-**Tier:** scaffold · **Category:** `applications-collab`
+**Category:** General
-## Role
+```mermaid
 flowchart LR
  App[Application] --> Mod[HyperP2PCollabRoom]
  Mod --> Mux[Protomux collab-room/v1]
  Mux --> Swarm[Hyperswarm]
 ```
-Collaboration room primitive.
+## Sequence (P2P)
 ```mermaid
 sequenceDiagram
  participant App
  participant Mod as Module
  participant SW as Hyperswarm
  participant Peer
  App->>Mod: ready(topic)
  Mod->>SW: join(topic)
  SW->>Peer: connection
  Mod->>Peer: gossip / Protomux
  Peer-->>Mod: onmessage
  Mod-->>App: emit(event)
 ```
 ## Wire messages
 | type | fields | direction | behavior |
 |------|--------|-----------|----------|
 | `broadcast` | event, roomId | gossip | Handled in onmessage / gossipSend |
 | `join` | event, member, peer, roomId, type | gossip | Handled in onmessage / gossipSend |
 | `leave` | event, peer, roomId, type | gossip | Handled in onmessage / gossipSend |
 ## State model
 - In-memory `Map` / `Set` structures for hot path
 - Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
 - `close()` tears down swarm, timers, and clears ephemeral state
 ## Composition
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
+Composes with: see MODULE_CATEGORIES.md.
 ## Holepunch boundary
 Inspiration: n/a
@@ -3,3 +3,7 @@
 ## [0.0.0-scaffold] — Wave 8
 - Registry scaffold: file tree, load smoke tests, docs stubs
 ## [0.3.2] - 2026-05-21
 ### Changed
 - Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
@@ -1,28 +1,41 @@
 # hyper-p2p-cursor-presence
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `cursor-presence/v1` · **Wave:** 8
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-Collaborative cursor presence.
+**Category:** General
-## Holepunch references (inspiration only)
+**Composes with:** 
- `hyper-p2p-presence`
+**Protocol:** `cursor-presence/v1`
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+## When to use
-## Composes with
+Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-whiteboard-op`
+## When not to use
-## Planned API
+Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair
+## Quick start
 - `getStats()` — scaffold counters
 - `ready()` — no-op until implemented
 - Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
-## Layout
+```js
 const { HyperP2PCursorPresence } = require('hyper-p2p-cursor-presence')
 const topic = process.argv[2] // 64-char hex or string
 const mod = new HyperP2PCursorPresence({ topic, enableBackgroundTimers: false })
 await mod.ready()   // joins swarm when topic set
 // ... application logic ...
 await mod.close()
 ```
-`modules/applications-collab/hyper-p2p-cursor-presence/`
+## Docs
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+- [docs/api.md](docs/api.md) — constructor, methods, events, errors
 - [docs/architecture.md](docs/architecture.md) — wire types, state, composition
 - [../../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
 - [../../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
 ## Test
 ```bash
 npm install && npm test
 ```
@@ -1,23 +1,83 @@
-# hyper-p2p-cursor-presence API
+# API: hyper-p2p-cursor-presence
-**Status:** scaffold · **Protocol:** `cursor-presence/v1`
+**Protocol:** `cursor-presence/v1`
-## Class `HyperP2PCursorPresence`
+**Export:** `HyperP2PCursorPresence`
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+## Overview
-### `constructor(opts?)`
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-### `getStats()`
+## Constructor
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+```js
 const mod = new HyperP2PCursorPresence(opts)
 ```
-### `ready()`
+| Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `topic` | varies | null | topic |
 | `keyPair` | KeyPair | random Ed25519 | keyPair |
-Resolves immediately (no-op).
+## Methods
-## Wire (planned)
+### `updateCursor(docId, position = {})`
-| Message | Direction | Notes |
+- **Returns:** `value`
-|---------|-----------|-------|
+- **Throws:** — (none documented in method body)
-| TBD | gossip | Defined in implementation pass |
+
 ### `getCursor(docId, peerHex)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `listCursors(docId)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `removeCursor(docId, peerHex = this.peerHex)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getStats(—)`
 - **Returns:** `object`
 - **Throws:** — (none documented in method body)
 ### `ready(—)`
 - **Returns:** `Promise`
 - **Throws:** — (none documented in method body)
 ### `close(—)`
 - **Returns:** `Promise<void>`
 - **Throws:** — (none documented in method body)
 ## Events
 | Event | Payload |
 |-------|---------|
 | `cursor` | entry |
 | `remote-cursor` | data.entry |
 ## getStats()
 Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
 Library-only modules may include `mode: 'local'`.
 ## Errors
 Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 ## P2P
 When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `cursor-presence/v1`.
 ## Testing
 ```bash
 npm install && npm test
 ```
@@ -1,15 +1,44 @@
-# hyper-p2p-cursor-presence architecture
+# Architecture: hyper-p2p-cursor-presence
-**Tier:** scaffold · **Category:** `applications-collab`
+**Category:** General
-## Role
+```mermaid
 flowchart LR
  App[Application] --> Mod[HyperP2PCursorPresence]
  Mod --> Mux[Protomux cursor-presence/v1]
  Mux --> Swarm[Hyperswarm]
 ```
-Collaborative cursor presence.
+## Sequence (P2P)
 ```mermaid
 sequenceDiagram
  participant App
  participant Mod as Module
  participant SW as Hyperswarm
  participant Peer
  App->>Mod: ready(topic)
  Mod->>SW: join(topic)
  SW->>Peer: connection
  Mod->>Peer: gossip / Protomux
  Peer-->>Mod: onmessage
  Mod-->>App: emit(event)
 ```
 ## Wire messages
 | type | fields | direction | behavior |
 |------|--------|-----------|----------|
 | `cursor` | docId, entry, peer, type | gossip | Handled in onmessage / gossipSend |
 | `cursor-remove` | docId, peer | gossip | Handled in onmessage / gossipSend |
 ## State model
 - In-memory `Map` / `Set` structures for hot path
 - Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
 - `close()` tears down swarm, timers, and clears ephemeral state
 ## Composition
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
+Composes with: see MODULE_CATEGORIES.md.
 ## Holepunch boundary
 Inspiration: n/a
@@ -3,3 +3,7 @@
 ## [0.0.0-scaffold] — Wave 8
 - Registry scaffold: file tree, load smoke tests, docs stubs
 ## [0.3.2] - 2026-05-21
 ### Changed
 - Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
@@ -1,28 +1,41 @@
 # hyper-p2p-document-line-lock
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `document-line-lock/v1` · **Wave:** 8
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-Per-line document locks.
+**Category:** General
-## Holepunch references (inspiration only)
+**Composes with:** 
- `hyper-p2p-distributed-lock`
+**Protocol:** `document-line-lock/v1`
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+## When to use
-## Composes with
+Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-whiteboard-op`
+## When not to use
-## Planned API
+Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair
+## Quick start
 - `getStats()` — scaffold counters
 - `ready()` — no-op until implemented
 - Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
-## Layout
+```js
 const { HyperP2PDocumentLineLock } = require('hyper-p2p-document-line-lock')
 const topic = process.argv[2] // 64-char hex or string
 const mod = new HyperP2PDocumentLineLock({ topic, enableBackgroundTimers: false })
 await mod.ready()   // joins swarm when topic set
 // ... application logic ...
 await mod.close()
 ```
-`modules/applications-collab/hyper-p2p-document-line-lock/`
+## Docs
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+- [docs/api.md](docs/api.md) — constructor, methods, events, errors
 - [docs/architecture.md](docs/architecture.md) — wire types, state, composition
 - [../../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
 - [../../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
 ## Test
 ```bash
 npm install && npm test
 ```
@@ -1,23 +1,85 @@
-# hyper-p2p-document-line-lock API
+# API: hyper-p2p-document-line-lock
-**Status:** scaffold · **Protocol:** `document-line-lock/v1`
+**Protocol:** `document-line-lock/v1`
-## Class `HyperP2PDocumentLineLock`
+**Export:** `HyperP2PDocumentLineLock`
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+## Overview
-### `constructor(opts?)`
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-### `getStats()`
+## Constructor
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+```js
 const mod = new HyperP2PDocumentLineLock(opts)
 ```
-### `ready()`
+| Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `topic` | varies | null | topic |
 | `keyPair` | KeyPair | random Ed25519 | keyPair |
-Resolves immediately (no-op).
+## Methods
-## Wire (planned)
+### `acquire(docId, line)`
-| Message | Direction | Notes |
+- **Returns:** `value`
-|---------|-----------|-------|
+- **Throws:** — (none documented in method body)
-| TBD | gossip | Defined in implementation pass |
+
 ### `release(docId, line)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `isLocked(docId, line)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getLock(docId, line)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getStats(—)`
 - **Returns:** `object`
 - **Throws:** — (none documented in method body)
 ### `ready(—)`
 - **Returns:** `Promise`
 - **Throws:** — (none documented in method body)
 ### `close(—)`
 - **Returns:** `Promise<void>`
 - **Throws:** — (none documented in method body)
 ## Events
 | Event | Payload |
 |-------|---------|
 | `acquire` | lock |
 | `release` | payload object |
 | `remote-acquire` | data.lock |
 | `remote-release` | data |
 ## getStats()
 Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
 Library-only modules may include `mode: 'local'`.
 ## Errors
 Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 ## P2P
 When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `document-line-lock/v1`.
 ## Testing
 ```bash
 npm install && npm test
 ```
@@ -1,15 +1,44 @@
-# hyper-p2p-document-line-lock architecture
+# Architecture: hyper-p2p-document-line-lock
-**Tier:** scaffold · **Category:** `applications-collab`
+**Category:** General
-## Role
+```mermaid
 flowchart LR
  App[Application] --> Mod[HyperP2PDocumentLineLock]
  Mod --> Mux[Protomux document-line-lock/v1]
  Mux --> Swarm[Hyperswarm]
 ```
-Per-line document locks.
+## Sequence (P2P)
 ```mermaid
 sequenceDiagram
  participant App
  participant Mod as Module
  participant SW as Hyperswarm
  participant Peer
  App->>Mod: ready(topic)
  Mod->>SW: join(topic)
  SW->>Peer: connection
  Mod->>Peer: gossip / Protomux
  Peer-->>Mod: onmessage
  Mod-->>App: emit(event)
 ```
 ## Wire messages
 | type | fields | direction | behavior |
 |------|--------|-----------|----------|
 | `line-lock` | docId, line, lock, type | gossip | Handled in onmessage / gossipSend |
 | `line-unlock` | docId, line | gossip | Handled in onmessage / gossipSend |
 ## State model
 - In-memory `Map` / `Set` structures for hot path
 - Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
 - `close()` tears down swarm, timers, and clears ephemeral state
 ## Composition
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
+Composes with: see MODULE_CATEGORIES.md.
 ## Holepunch boundary
 Inspiration: n/a
@@ -3,3 +3,7 @@
 ## [0.0.0-scaffold] — Wave 8
 - Registry scaffold: file tree, load smoke tests, docs stubs
 ## [0.3.2] - 2026-05-21
 ### Changed
 - Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
@@ -1,28 +1,43 @@
 # hyper-p2p-whiteboard-op
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `whiteboard-op/v1` · **Wave:** 8
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-Whiteboard operation CRDT.
+**Category:** General
-## Holepunch references (inspiration only)
+**Composes with:** 
- `hyperdispatch`
+**Protocol:** `whiteboard-op/v1`
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+## When to use
-## Composes with
+Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-reactive-state`
+## When not to use
-## Planned API
+Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair
+## Quick start
 - `getStats()` — scaffold counters
 - `ready()` — no-op until implemented
 - Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
-## Layout
+```js
 const { HyperP2PWhiteboardOp } = require('hyper-p2p-whiteboard-op')
 const topic = process.argv[2] // 64-char hex or string
 const mod = new HyperP2PWhiteboardOp({ topic, enableBackgroundTimers: false })
 await mod.ready()   // joins swarm when topic set
 // ... application logic ...
 await mod.close()
 ```
-`modules/applications-collab/hyper-p2p-whiteboard-op/`
+## Docs
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+- [docs/api.md](docs/api.md) — constructor, methods, events, errors
 - [docs/architecture.md](docs/architecture.md) — wire types, state, composition
 - [../../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
 - [../../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
 - Integration: [`../../real_tests/integration/`](../../real_tests/integration/) — `whiteboard-op-two-node.js`
 ## Test
 ```bash
 npm install && npm test
 ```
@@ -1,23 +1,80 @@
-# hyper-p2p-whiteboard-op API
+# API: hyper-p2p-whiteboard-op
-**Status:** scaffold · **Protocol:** `whiteboard-op/v1`
+**Protocol:** `whiteboard-op/v1`
-## Class `HyperP2PWhiteboardOp`
+**Export:** `HyperP2PWhiteboardOp`
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+## Overview
-### `constructor(opts?)`
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-### `getStats()`
+## Constructor
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+```js
 const mod = new HyperP2PWhiteboardOp(opts)
 ```
-### `ready()`
+| Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `topic` | varies | null | topic |
 | `keyPair` | KeyPair | random Ed25519 | keyPair |
-Resolves immediately (no-op).
+## Methods
-## Wire (planned)
+### `apply(roomId, op)`
-| Message | Direction | Notes |
+- **Returns:** `value`
-|---------|-----------|-------|
+- **Throws:**
-| TBD | gossip | Defined in implementation pass |
+  - `Error: op object required`
 ### `history(roomId, limit = 100)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `mergeRemote(entry)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getStats(—)`
 - **Returns:** `object`
 - **Throws:** — (none documented in method body)
 ### `ready(—)`
 - **Returns:** `Promise`
 - **Throws:** — (none documented in method body)
 ### `close(—)`
 - **Returns:** `Promise<void>`
 - **Throws:** — (none documented in method body)
 ## Events
 | Event | Payload |
 |-------|---------|
 | `op` | remote |
 ## getStats()
 Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
 Library-only modules may include `mode: 'local'`.
 ## Errors
 Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 ## P2P
 When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `whiteboard-op/v1`.
 ## Testing
 ```bash
 npm install && npm test
 ```
 Integration: [`../../../real_tests/integration/whiteboard-op-two-node.js`](../../../real_tests/integration/whiteboard-op-two-node.js)
@@ -1,15 +1,43 @@
-# hyper-p2p-whiteboard-op architecture
+# Architecture: hyper-p2p-whiteboard-op
-**Tier:** scaffold · **Category:** `applications-collab`
+**Category:** General
-## Role
+```mermaid
 flowchart LR
  App[Application] --> Mod[HyperP2PWhiteboardOp]
  Mod --> Mux[Protomux whiteboard-op/v1]
  Mux --> Swarm[Hyperswarm]
 ```
-Whiteboard operation CRDT.
+## Sequence (P2P)
 ```mermaid
 sequenceDiagram
  participant App
  participant Mod as Module
  participant SW as Hyperswarm
  participant Peer
  App->>Mod: ready(topic)
  Mod->>SW: join(topic)
  SW->>Peer: connection
  Mod->>Peer: gossip / Protomux
  Peer-->>Mod: onmessage
  Mod-->>App: emit(event)
 ```
 ## Wire messages
 | type | fields | direction | behavior |
 |------|--------|-----------|----------|
 | `wb-op` | entry | gossip | Handled in onmessage / gossipSend |
 ## State model
 - In-memory `Map` / `Set` structures for hot path
 - Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
 - `close()` tears down swarm, timers, and clears ephemeral state
 ## Composition
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
+Composes with: see MODULE_CATEGORIES.md.
 ## Holepunch boundary
 Inspiration: n/a
@@ -3,3 +3,7 @@
 ## [0.0.0-scaffold] — Wave 8
 - Registry scaffold: file tree, load smoke tests, docs stubs
 ## [0.3.2] - 2026-05-21
 ### Changed
 - Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
@@ -1,28 +1,41 @@
 # hyper-p2p-compact-codec-bridge
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `compact-codec-bridge/v1` · **Wave:** 8
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-Compact-encoding bridge.
+**Category:** General
-## Holepunch references (inspiration only)
+**Composes with:** 
- `compact-encoding`
+**Protocol:** `compact-codec-bridge/v1`
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+## When to use
-## Composes with
+Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-rpc`
+## When not to use
-## Planned API
+Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair
+## Quick start
 - `getStats()` — scaffold counters
 - `ready()` — no-op until implemented
 - Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
-## Layout
+```js
 const { HyperP2PCompactCodecBridge } = require('hyper-p2p-compact-codec-bridge')
 const topic = process.argv[2] // 64-char hex or string
 const mod = new HyperP2PCompactCodecBridge({ topic, enableBackgroundTimers: false })
 await mod.ready()   // joins swarm when topic set
 // ... application logic ...
 await mod.close()
 ```
-`modules/encoding-wire/hyper-p2p-compact-codec-bridge/`
+## Docs
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+- [docs/api.md](docs/api.md) — constructor, methods, events, errors
 - [docs/architecture.md](docs/architecture.md) — wire types, state, composition
 - [../../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
 - [../../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
 ## Test
 ```bash
 npm install && npm test
 ```
@@ -1,23 +1,72 @@
-# hyper-p2p-compact-codec-bridge API
+# API: hyper-p2p-compact-codec-bridge
-**Status:** scaffold · **Protocol:** `compact-codec-bridge/v1`
+**Protocol:** `compact-codec-bridge/v1`
-## Class `HyperP2PCompactCodecBridge`
+**Export:** `HyperP2PCompactCodecBridge`
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+## Overview
-### `constructor(opts?)`
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-### `getStats()`
+## Constructor
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+```js
 const mod = new HyperP2PCompactCodecBridge(opts)
 ```
-### `ready()`
+| Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
 | `keyPair` | KeyPair | random | Ed25519 key pair |
 | `registry` | varies | new HyperP2PWireRegistry() | registry |
-Resolves immediately (no-op).
+## Methods
-## Wire (planned)
+### `encode(codecId, value)`
-| Message | Direction | Notes |
+- **Returns:** `value`
-|---------|-----------|-------|
+- **Throws:** — (none documented in method body)
-| TBD | gossip | Defined in implementation pass |
+
 ### `decode(codecId, buf)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getStats(—)`
 - **Returns:** `object`
 - **Throws:** — (none documented in method body)
 ### `ready(—)`
 - **Returns:** `Promise`
 - **Throws:** — (none documented in method body)
 ### `close(—)`
 - **Returns:** `Promise<void>`
 - **Throws:** — (none documented in method body)
 ## Events
 | Event | Payload |
 |-------|---------|
 ## getStats()
 Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
 Library-only modules may include `mode: 'local'`.
 ## Errors
 Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 ## P2P
 When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `compact-codec-bridge/v1`.
 ## Testing
 ```bash
 npm install && npm test
 ```
@@ -1,15 +1,27 @@
-# hyper-p2p-compact-codec-bridge architecture
+# Architecture: hyper-p2p-compact-codec-bridge
-**Tier:** scaffold · **Category:** `encoding-wire`
+**Category:** General
-## Role
+```mermaid
 flowchart LR
  App[Application] --> Mod[HyperP2PCompactCodecBridge]
  Mod --> Mux[Protomux compact-codec-bridge/v1]
  Mux --> Swarm[Hyperswarm]
 ```
-Compact-encoding bridge.
+## Wire messages
 | type | fields | direction | behavior |
 |------|--------|-----------|----------|
 | *(local only)* | — | — | No gossip wire types |
 ## State model
 - In-memory `Map` / `Set` structures for hot path
 - Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
 - `close()` tears down swarm, timers, and clears ephemeral state
 ## Composition
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
+Composes with: see MODULE_CATEGORIES.md.
 ## Holepunch boundary
 Inspiration: n/a
@@ -3,3 +3,7 @@
 ## [0.0.0-scaffold] — Wave 8
 - Registry scaffold: file tree, load smoke tests, docs stubs
 ## [0.3.2] - 2026-05-21
 ### Changed
 - Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
@@ -1,28 +1,41 @@
 # hyper-p2p-schema-validator
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `schema-validator/v1` · **Wave:** 8
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-Schema validation for payloads.
+**Category:** General
-## Holepunch references (inspiration only)
+**Composes with:** 
- `hyperschema`
+**Protocol:** `schema-validator/v1`
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+## When to use
-## Composes with
+Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-rpc`
+## When not to use
-## Planned API
+Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair
+## Quick start
 - `getStats()` — scaffold counters
 - `ready()` — no-op until implemented
 - Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
-## Layout
+```js
 const { HyperP2PSchemaValidator } = require('hyper-p2p-schema-validator')
 const topic = process.argv[2] // 64-char hex or string
 const mod = new HyperP2PSchemaValidator({ topic, enableBackgroundTimers: false })
 await mod.ready()   // joins swarm when topic set
 // ... application logic ...
 await mod.close()
 ```
-`modules/encoding-wire/hyper-p2p-schema-validator/`
+## Docs
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+- [docs/api.md](docs/api.md) — constructor, methods, events, errors
 - [docs/architecture.md](docs/architecture.md) — wire types, state, composition
 - [../../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
 - [../../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
 ## Test
 ```bash
 npm install && npm test
 ```
@@ -1,23 +1,73 @@
-# hyper-p2p-schema-validator API
+# API: hyper-p2p-schema-validator
-**Status:** scaffold · **Protocol:** `schema-validator/v1`
+**Protocol:** `schema-validator/v1`
-## Class `HyperP2PSchemaValidator`
+**Export:** `HyperP2PSchemaValidator`
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+## Overview
-### `constructor(opts?)`
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-### `getStats()`
+## Constructor
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+```js
 const mod = new HyperP2PSchemaValidator(opts)
 ```
-### `ready()`
+| Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
 | `keyPair` | KeyPair | random | Ed25519 key pair |
-Resolves immediately (no-op).
+## Methods
-## Wire (planned)
+### `register(name, schema)`
-| Message | Direction | Notes |
+- **Returns:** `value`
-|---------|-----------|-------|
+- **Throws:**
-| TBD | gossip | Defined in implementation pass |
+  - `Error: schema object required`
 ### `validate(name, value)`
 - **Returns:** `value`
 - **Throws:**
  - `Error: unknown schema`
 ### `getStats(—)`
 - **Returns:** `object`
 - **Throws:** — (none documented in method body)
 ### `ready(—)`
 - **Returns:** `Promise`
 - **Throws:** — (none documented in method body)
 ### `close(—)`
 - **Returns:** `Promise<void>`
 - **Throws:** — (none documented in method body)
 ## Events
 | Event | Payload |
 |-------|---------|
 ## getStats()
 Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
 Library-only modules may include `mode: 'local'`.
 ## Errors
 Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 ## P2P
 When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `schema-validator/v1`.
 ## Testing
 ```bash
 npm install && npm test
 ```
@@ -1,15 +1,27 @@
-# hyper-p2p-schema-validator architecture
+# Architecture: hyper-p2p-schema-validator
-**Tier:** scaffold · **Category:** `encoding-wire`
+**Category:** General
-## Role
+```mermaid
 flowchart LR
  App[Application] --> Mod[HyperP2PSchemaValidator]
  Mod --> Mux[Protomux schema-validator/v1]
  Mux --> Swarm[Hyperswarm]
 ```
-Schema validation for payloads.
+## Wire messages
 | type | fields | direction | behavior |
 |------|--------|-----------|----------|
 | *(local only)* | — | — | No gossip wire types |
 ## State model
 - In-memory `Map` / `Set` structures for hot path
 - Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
 - `close()` tears down swarm, timers, and clears ephemeral state
 ## Composition
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
+Composes with: see MODULE_CATEGORIES.md.
 ## Holepunch boundary
 Inspiration: n/a
@@ -3,3 +3,7 @@
 ## [0.0.0-scaffold] — Wave 8
 - Registry scaffold: file tree, load smoke tests, docs stubs
 ## [0.3.2] - 2026-05-21
 ### Changed
 - Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
@@ -1,28 +1,41 @@
 # hyper-p2p-wire-registry
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `wire-registry/v1` · **Wave:** 8
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-Wire type registry.
+**Category:** General
-## Holepunch references (inspiration only)
+**Composes with:** 
- `compact-encoding`
+**Protocol:** `wire-registry/v1`
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+## When to use
-## Composes with
+Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-protocol-handshake`
+## When not to use
-## Planned API
+Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair
+## Quick start
 - `getStats()` — scaffold counters
 - `ready()` — no-op until implemented
 - Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
-## Layout
+```js
 const { HyperP2PWireRegistry } = require('hyper-p2p-wire-registry')
 const topic = process.argv[2] // 64-char hex or string
 const mod = new HyperP2PWireRegistry({ topic, enableBackgroundTimers: false })
 await mod.ready()   // joins swarm when topic set
 // ... application logic ...
 await mod.close()
 ```
-`modules/encoding-wire/hyper-p2p-wire-registry/`
+## Docs
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+- [docs/api.md](docs/api.md) — constructor, methods, events, errors
 - [docs/architecture.md](docs/architecture.md) — wire types, state, composition
 - [../../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
 - [../../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
 ## Test
 ```bash
 npm install && npm test
 ```
@@ -1,23 +1,100 @@
-# hyper-p2p-wire-registry API
+# API: hyper-p2p-wire-registry
-**Status:** scaffold · **Protocol:** `wire-registry/v1`
+**Protocol:** `wire-registry/v1`
-## Class `HyperP2PWireRegistry`
+**Export:** `HyperP2PWireRegistry`
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+## Overview
-### `constructor(opts?)`
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-### `getStats()`
+## Constructor
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+```js
 const mod = new HyperP2PWireRegistry(opts)
 ```
-### `ready()`
+| Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
 | `keyPair` | KeyPair | random | Ed25519 key pair |
-Resolves immediately (no-op).
+## Methods
-## Wire (planned)
+### `registerCodec(id, codec)`
-| Message | Direction | Notes |
+- **Returns:** `value`
-|---------|-----------|-------|
+- **Throws:**
-| TBD | gossip | Defined in implementation pass |
+  - `Error: codec required`
 ### `registerProtocol(protocolId, meta = {})`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `hasProtocol(protocolId)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `encode(id, value)`
 - **Returns:** `value`
 - **Throws:**
  - `Error: unknown codec id`
 ### `decode(id, buf)`
 - **Returns:** `value`
 - **Throws:**
  - `Error: unknown codec id`
 ### `listProtocols(—)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `negotiate(offered = [])`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getStats(—)`
 - **Returns:** `object`
 - **Throws:** — (none documented in method body)
 ### `ready(—)`
 - **Returns:** `Promise`
 - **Throws:** — (none documented in method body)
 ### `close(—)`
 - **Returns:** `Promise<void>`
 - **Throws:** — (none documented in method body)
 ## Events
 | Event | Payload |
 |-------|---------|
 | `protocol` | payload object |
 ## getStats()
 Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
 Library-only modules may include `mode: 'local'`.
 ## Errors
 Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 ## P2P
 When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `wire-registry/v1`.
 ## Testing
 ```bash
 npm install && npm test
 ```
@@ -1,15 +1,27 @@
-# hyper-p2p-wire-registry architecture
+# Architecture: hyper-p2p-wire-registry
-**Tier:** scaffold · **Category:** `encoding-wire`
+**Category:** General
-## Role
+```mermaid
 flowchart LR
  App[Application] --> Mod[HyperP2PWireRegistry]
  Mod --> Mux[Protomux wire-registry/v1]
  Mux --> Swarm[Hyperswarm]
 ```
-Wire type registry.
+## Wire messages
 | type | fields | direction | behavior |
 |------|--------|-----------|----------|
 | *(local only)* | — | — | No gossip wire types |
 ## State model
 - In-memory `Map` / `Set` structures for hot path
 - Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
 - `close()` tears down swarm, timers, and clears ephemeral state
 ## Composition
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
+Composes with: see MODULE_CATEGORIES.md.
 ## Holepunch boundary
 Inspiration: n/a
@@ -3,3 +3,7 @@
 ## [0.0.0-scaffold] — Wave 8
 - Registry scaffold: file tree, load smoke tests, docs stubs
 ## [0.3.2] - 2026-05-21
 ### Changed
 - Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
@@ -1,28 +1,43 @@
 # hyper-p2p-qos-topic
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `qos-topic/v1` · **Wave:** 8
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-QoS tiers per topic.
+**Category:** General
-## Holepunch references (inspiration only)
+**Composes with:** 
- `protomux`
+**Protocol:** `qos-topic/v1`
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+## When to use
-## Composes with
+Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-flow-shaper`
+## When not to use
-## Planned API
+Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair
+## Quick start
 - `getStats()` — scaffold counters
 - `ready()` — no-op until implemented
 - Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
-## Layout
+```js
 const { HyperP2PQosTopic } = require('hyper-p2p-qos-topic')
 const topic = process.argv[2] // 64-char hex or string
 const mod = new HyperP2PQosTopic({ topic, enableBackgroundTimers: false })
 await mod.ready()   // joins swarm when topic set
 // ... application logic ...
 await mod.close()
 ```
-`modules/messaging-pubsub/hyper-p2p-qos-topic/`
+## Docs
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+- [docs/api.md](docs/api.md) — constructor, methods, events, errors
 - [docs/architecture.md](docs/architecture.md) — wire types, state, composition
 - [../../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
 - [../../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
 - Integration: [`../../real_tests/integration/`](../../real_tests/integration/) — `qos-topic-two-node.js`
 ## Test
 ```bash
 npm install && npm test
 ```
@@ -1,23 +1,80 @@
-# hyper-p2p-qos-topic API
+# API: hyper-p2p-qos-topic
-**Status:** scaffold · **Protocol:** `qos-topic/v1`
+**Protocol:** `qos-topic/v1`
-## Class `HyperP2PQosTopic`
+**Export:** `HyperP2PQosTopic`
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+## Overview
-### `constructor(opts?)`
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-### `getStats()`
+## Constructor
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+```js
 const mod = new HyperP2PQosTopic(opts)
 ```
-### `ready()`
+| Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `topic` | varies | null | topic |
 | `keyPair` | KeyPair | random Ed25519 | keyPair |
-Resolves immediately (no-op).
+## Methods
-## Wire (planned)
+### `subscribe(channel, handler, qos = 0)`
-| Message | Direction | Notes |
+- **Returns:** `value`
-|---------|-----------|-------|
+- **Throws:**
-| TBD | gossip | Defined in implementation pass |
+  - `Error: handler must be a function`
 ### `publish(channel, payload, opts = {})`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `pending(qos)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getStats(—)`
 - **Returns:** `object`
 - **Throws:** — (none documented in method body)
 ### `ready(—)`
 - **Returns:** `Promise`
 - **Throws:** — (none documented in method body)
 ### `close(—)`
 - **Returns:** `Promise<void>`
 - **Throws:** — (none documented in method body)
 ## Events
 | Event | Payload |
 |-------|---------|
 | `message` | msg |
 ## getStats()
 Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
 Library-only modules may include `mode: 'local'`.
 ## Errors
 Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 ## P2P
 When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `qos-topic/v1`.
 ## Testing
 ```bash
 npm install && npm test
 ```
 Integration: [`../../../real_tests/integration/qos-topic-two-node.js`](../../../real_tests/integration/qos-topic-two-node.js)
@@ -1,15 +1,43 @@
-# hyper-p2p-qos-topic architecture
+# Architecture: hyper-p2p-qos-topic
-**Tier:** scaffold · **Category:** `messaging-pubsub`
+**Category:** General
-## Role
+```mermaid
 flowchart LR
  App[Application] --> Mod[HyperP2PQosTopic]
  Mod --> Mux[Protomux qos-topic/v1]
  Mux --> Swarm[Hyperswarm]
 ```
-QoS tiers per topic.
+## Sequence (P2P)
 ```mermaid
 sequenceDiagram
  participant App
  participant Mod as Module
  participant SW as Hyperswarm
  participant Peer
  App->>Mod: ready(topic)
  Mod->>SW: join(topic)
  SW->>Peer: connection
  Mod->>Peer: gossip / Protomux
  Peer-->>Mod: onmessage
  Mod-->>App: emit(event)
 ```
 ## Wire messages
 | type | fields | direction | behavior |
 |------|--------|-----------|----------|
 | `qos-publish` | at, from, type | gossip | Handled in onmessage / gossipSend |
 ## State model
 - In-memory `Map` / `Set` structures for hot path
 - Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
 - `close()` tears down swarm, timers, and clears ephemeral state
 ## Composition
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
+Composes with: see MODULE_CATEGORIES.md.
 ## Holepunch boundary
 Inspiration: n/a
@@ -3,3 +3,7 @@
 ## [0.0.0-scaffold] — Wave 8
 - Registry scaffold: file tree, load smoke tests, docs stubs
 ## [0.3.2] - 2026-05-21
 ### Changed
 - Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
@@ -1,28 +1,41 @@
 # hyper-p2p-retained-messages
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `retained-messages/v1` · **Wave:** 8
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-Retained message store.
+**Category:** General
-## Holepunch references (inspiration only)
+**Composes with:** 
- `protomux`
+**Protocol:** `retained-messages/v1`
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+## When to use
-## Composes with
+Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-gossip-mesh`
+## When not to use
-## Planned API
+Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair
+## Quick start
 - `getStats()` — scaffold counters
 - `ready()` — no-op until implemented
 - Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
-## Layout
+```js
 const { HyperP2PRetainedMessages } = require('hyper-p2p-retained-messages')
 const topic = process.argv[2] // 64-char hex or string
 const mod = new HyperP2PRetainedMessages({ topic, enableBackgroundTimers: false })
 await mod.ready()   // joins swarm when topic set
 // ... application logic ...
 await mod.close()
 ```
-`modules/messaging-pubsub/hyper-p2p-retained-messages/`
+## Docs
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+- [docs/api.md](docs/api.md) — constructor, methods, events, errors
 - [docs/architecture.md](docs/architecture.md) — wire types, state, composition
 - [../../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
 - [../../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
 ## Test
 ```bash
 npm install && npm test
 ```
@@ -1,23 +1,83 @@
-# hyper-p2p-retained-messages API
+# API: hyper-p2p-retained-messages
-**Status:** scaffold · **Protocol:** `retained-messages/v1`
+**Protocol:** `retained-messages/v1`
-## Class `HyperP2PRetainedMessages`
+**Export:** `HyperP2PRetainedMessages`
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+## Overview
-### `constructor(opts?)`
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-### `getStats()`
+## Constructor
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+```js
 const mod = new HyperP2PRetainedMessages(opts)
 ```
-### `ready()`
+| Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
 | `keyPair` | KeyPair | random | Ed25519 key pair |
 | `maxPerChannel` | number | 32 | maxPerChannel |
-Resolves immediately (no-op).
+## Methods
-## Wire (planned)
+### `retain(channel, payload, meta = {})`
-| Message | Direction | Notes |
+- **Returns:** `value`
-|---------|-----------|-------|
+- **Throws:** — (none documented in method body)
-| TBD | gossip | Defined in implementation pass |
+
 ### `latest(channel)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `list(channel, limit = 10)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `clear(channel)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getStats(—)`
 - **Returns:** `object`
 - **Throws:** — (none documented in method body)
 ### `ready(—)`
 - **Returns:** `Promise`
 - **Throws:** — (none documented in method body)
 ### `close(—)`
 - **Returns:** `Promise<void>`
 - **Throws:** — (none documented in method body)
 ## Events
 | Event | Payload |
 |-------|---------|
 | `retain` | payload object |
 ## getStats()
 Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
 Library-only modules may include `mode: 'local'`.
 ## Errors
 Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 ## P2P
 When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `retained-messages/v1`.
 ## Testing
 ```bash
 npm install && npm test
 ```
@@ -1,15 +1,27 @@
-# hyper-p2p-retained-messages architecture
+# Architecture: hyper-p2p-retained-messages
-**Tier:** scaffold · **Category:** `messaging-pubsub`
+**Category:** General
-## Role
+```mermaid
 flowchart LR
  App[Application] --> Mod[HyperP2PRetainedMessages]
  Mod --> Mux[Protomux retained-messages/v1]
  Mux --> Swarm[Hyperswarm]
 ```
-Retained message store.
+## Wire messages
 | type | fields | direction | behavior |
 |------|--------|-----------|----------|
 | *(local only)* | — | — | No gossip wire types |
 ## State model
 - In-memory `Map` / `Set` structures for hot path
 - Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
 - `close()` tears down swarm, timers, and clears ephemeral state
 ## Composition
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
+Composes with: see MODULE_CATEGORIES.md.
 ## Holepunch boundary
 Inspiration: n/a
@@ -3,3 +3,7 @@
 ## [0.0.0-scaffold] — Wave 8
 - Registry scaffold: file tree, load smoke tests, docs stubs
 ## [0.3.2] - 2026-05-21
 ### Changed
 - Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
@@ -1,28 +1,41 @@
 # hyper-p2p-subscription-lease
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `subscription-lease/v1` · **Wave:** 8
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-Subscription lease gossip.
+**Category:** General
-## Holepunch references (inspiration only)
+**Composes with:** 
- `protomux`
+**Protocol:** `subscription-lease/v1`
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+## When to use
-## Composes with
+Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-topic-lease`
+## When not to use
-## Planned API
+Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair
+## Quick start
 - `getStats()` — scaffold counters
 - `ready()` — no-op until implemented
 - Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
-## Layout
+```js
 const { HyperP2PSubscriptionLease } = require('hyper-p2p-subscription-lease')
 const topic = process.argv[2] // 64-char hex or string
 const mod = new HyperP2PSubscriptionLease({ topic, enableBackgroundTimers: false })
 await mod.ready()   // joins swarm when topic set
 // ... application logic ...
 await mod.close()
 ```
-`modules/messaging-pubsub/hyper-p2p-subscription-lease/`
+## Docs
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+- [docs/api.md](docs/api.md) — constructor, methods, events, errors
 - [docs/architecture.md](docs/architecture.md) — wire types, state, composition
 - [../../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
 - [../../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
 ## Test
 ```bash
 npm install && npm test
 ```
@@ -1,23 +1,86 @@
-# hyper-p2p-subscription-lease API
+# API: hyper-p2p-subscription-lease
-**Status:** scaffold · **Protocol:** `subscription-lease/v1`
+**Protocol:** `subscription-lease/v1`
-## Class `HyperP2PSubscriptionLease`
+**Export:** `HyperP2PSubscriptionLease`
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+## Overview
-### `constructor(opts?)`
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-### `getStats()`
+## Constructor
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+```js
 const mod = new HyperP2PSubscriptionLease(opts)
 ```
-### `ready()`
+| Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `topic` | varies | null | topic |
 | `keyPair` | KeyPair | random Ed25519 | keyPair |
 | `leaseMs` | varies | DEFAULT_LEASE_MS | lease (ms) |
 | `enableBackgroundTimers` | boolean | `false` | Periodic timers (off in tests) |
-Resolves immediately (no-op).
+## Methods
-## Wire (planned)
+### `acquire(channel)`
-| Message | Direction | Notes |
+- **Returns:** `value`
-|---------|-----------|-------|
+- **Throws:** — (none documented in method body)
-| TBD | gossip | Defined in implementation pass |
+
 ### `renew(channel)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `release(channel)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `holder(channel)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getStats(—)`
 - **Returns:** `object`
 - **Throws:** — (none documented in method body)
 ### `ready(—)`
 - **Returns:** `Promise`
 - **Throws:** — (none documented in method body)
 ### `close(—)`
 - **Returns:** `Promise<void>`
 - **Throws:** — (none documented in method body)
 ## Events
 | Event | Payload |
 |-------|---------|
 | `acquire` | lease |
 | `closed` | no payload |
 | `expired` | channel |
 ## getStats()
 Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
 Library-only modules may include `mode: 'local'`.
 ## Errors
 Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 ## P2P
 When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `subscription-lease/v1`.
 ## Testing
 ```bash
 npm install && npm test
 ```
@@ -1,15 +1,44 @@
-# hyper-p2p-subscription-lease architecture
+# Architecture: hyper-p2p-subscription-lease
-**Tier:** scaffold · **Category:** `messaging-pubsub`
+**Category:** General
-## Role
+```mermaid
 flowchart LR
  App[Application] --> Mod[HyperP2PSubscriptionLease]
  Mod --> Mux[Protomux subscription-lease/v1]
  Mux --> Swarm[Hyperswarm]
 ```
-Subscription lease gossip.
+## Sequence (P2P)
 ```mermaid
 sequenceDiagram
  participant App
  participant Mod as Module
  participant SW as Hyperswarm
  participant Peer
  App->>Mod: ready(topic)
  Mod->>SW: join(topic)
  SW->>Peer: connection
  Mod->>Peer: gossip / Protomux
  Peer-->>Mod: onmessage
  Mod-->>App: emit(event)
 ```
 ## Wire messages
 | type | fields | direction | behavior |
 |------|--------|-----------|----------|
 | `sub-lease` | channel, hol, lease, type | gossip | Handled in onmessage / gossipSend |
 | `sub-release` | channel, holder | gossip | Handled in onmessage / gossipSend |
 ## State model
 - In-memory `Map` / `Set` structures for hot path
 - Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
 - `close()` tears down swarm, timers, and clears ephemeral state
 ## Composition
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
+Composes with: see MODULE_CATEGORIES.md.
 ## Holepunch boundary
 Inspiration: n/a
@@ -3,3 +3,7 @@
 ## [0.0.0-scaffold] — Wave 8
 - Registry scaffold: file tree, load smoke tests, docs stubs
 ## [0.3.2] - 2026-05-21
 ### Changed
 - Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
@@ -1,28 +1,43 @@
 # hyper-p2p-topic-channel
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `topic-channel/v1` · **Wave:** 8
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-Named topic channels.
+**Category:** General
-## Holepunch references (inspiration only)
+**Composes with:** 
- `protomux`
+**Protocol:** `topic-channel/v1`
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+## When to use
-## Composes with
+Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-gossip-mesh`
+## When not to use
-## Planned API
+Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair
+## Quick start
 - `getStats()` — scaffold counters
 - `ready()` — no-op until implemented
 - Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
-## Layout
+```js
 const { HyperP2PTopicChannel } = require('hyper-p2p-topic-channel')
 const topic = process.argv[2] // 64-char hex or string
 const mod = new HyperP2PTopicChannel({ topic, enableBackgroundTimers: false })
 await mod.ready()   // joins swarm when topic set
 // ... application logic ...
 await mod.close()
 ```
-`modules/messaging-pubsub/hyper-p2p-topic-channel/`
+## Docs
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+- [docs/api.md](docs/api.md) — constructor, methods, events, errors
 - [docs/architecture.md](docs/architecture.md) — wire types, state, composition
 - [../../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
 - [../../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
 - Integration: [`../../real_tests/integration/`](../../real_tests/integration/) — `topic-channel-two-node.js`
 ## Test
 ```bash
 npm install && npm test
 ```
@@ -1,23 +1,91 @@
-# hyper-p2p-topic-channel API
+# API: hyper-p2p-topic-channel
-**Status:** scaffold · **Protocol:** `topic-channel/v1`
+**Protocol:** `topic-channel/v1`
-## Class `HyperP2PTopicChannel`
+**Export:** `HyperP2PTopicChannel`
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+## Overview
-### `constructor(opts?)`
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-### `getStats()`
+## Constructor
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+```js
 const mod = new HyperP2PTopicChannel(opts)
 ```
-### `ready()`
+| Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `topic` | varies | null | topic |
 | `keyPair` | KeyPair | random Ed25519 | keyPair |
-Resolves immediately (no-op).
+## Methods
-## Wire (planned)
+### `subscribe(channel, handler)`
-| Message | Direction | Notes |
+- **Returns:** `value`
-|---------|-----------|-------|
+- **Throws:**
-| TBD | gossip | Defined in implementation pass |
+  - `Error: handler must be a function`
 ### `unsubscribe(channel)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `publish(channel, payload, opts = {})`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getRetained(channel)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `syncRetained(channel)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getStats(—)`
 - **Returns:** `object`
 - **Throws:** — (none documented in method body)
 ### `ready(—)`
 - **Returns:** `Promise`
 - **Throws:** — (none documented in method body)
 ### `close(—)`
 - **Returns:** `Promise<void>`
 - **Throws:** — (none documented in method body)
 ## Events
 | Event | Payload |
 |-------|---------|
 | `closed` | no payload |
 | `message` | payload object |
 ## getStats()
 Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
 Library-only modules may include `mode: 'local'`.
 ## Errors
 Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 ## P2P
 When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `topic-channel/v1`.
 ## Testing
 ```bash
 npm install && npm test
 ```
 Integration: [`../../../real_tests/integration/topic-channel-two-node.js`](../../../real_tests/integration/topic-channel-two-node.js)
@@ -1,22 +1,46 @@
-# hyper-p2p-topic-channel architecture
+# Architecture: hyper-p2p-topic-channel
-**Tier:** production · **Category:** `messaging-pubsub` · **Protocol:** `topic-channel/v1`
+**Category:** General
-## Role
+```mermaid
 flowchart LR
  App[Application] --> Mod[HyperP2PTopicChannel]
  Mod --> Mux[Protomux topic-channel/v1]
  Mux --> Swarm[Hyperswarm]
 ```
-Named topic channels over Hyperswarm + Protomux: subscribe, publish, optional retained messages per channel.
+## Sequence (P2P)
 ```mermaid
 sequenceDiagram
  participant App
  participant Mod as Module
  participant SW as Hyperswarm
  participant Peer
  App->>Mod: ready(topic)
  Mod->>SW: join(topic)
  SW->>Peer: connection
  Mod->>Peer: gossip / Protomux
  Peer-->>Mod: onmessage
  Mod-->>App: emit(event)
 ```
 ## Wire messages
-| type | Direction | Fields |
+| type | fields | direction | behavior |
-|------|-----------|--------|
+|------|--------|-----------|----------|
-| `subscribe` | gossip | `channel`, `peer` |
+| `publish` | at, channe, channel, payload, qos, retain, type | gossip | Handled in onmessage / gossipSend |
-| `unsubscribe` | gossip | `channel`, `peer` |
+| `retained-sync` | at, channel, from, payload | gossip | Handled in onmessage / gossipSend |
-| `publish` | gossip | `channel`, `payload`, `from`, `at`, `qos`, `retain` |
+| `subscribe` | peer, type | gossip | Handled in onmessage / gossipSend |
-| `retained-sync` | gossip | `channel`, `payload`, `from`, `at` |
+| `unsubscribe` | peer, type | gossip | Handled in onmessage / gossipSend |
 ## State model
 - In-memory `Map` / `Set` structures for hot path
 - Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
 - `close()` tears down swarm, timers, and clears ephemeral state
 ## Composition
-Composes with `hyper-p2p-gossip-mesh`, `hyper-p2p-topic-lease`, `hyper-p2p-subscription-lease`.
+Composes with: see MODULE_CATEGORIES.md.
 Uses `../../_shared/p2p-bare.js` (`initModuleSwarm`, `gossipSend`).
@@ -3,3 +3,7 @@
 ## [0.0.0-scaffold] — Wave 8
 - Registry scaffold: file tree, load smoke tests, docs stubs
 ## [0.3.2] - 2026-05-21
 ### Changed
 - Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
@@ -1,28 +1,41 @@
 # hyper-p2p-stream-backpressure
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `stream-backpressure/v1` · **Wave:** 8
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-Backpressure for P2P streams.
+**Category:** General
-## Holepunch references (inspiration only)
+**Composes with:** 
- `protomux`
+**Protocol:** `stream-backpressure/v1`
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+## When to use
-## Composes with
+Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-flow-shaper`
+## When not to use
-## Planned API
+Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair
+## Quick start
 - `getStats()` — scaffold counters
 - `ready()` — no-op until implemented
 - Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
-## Layout
+```js
 const { HyperP2PStreamBackpressure } = require('hyper-p2p-stream-backpressure')
 const topic = process.argv[2] // 64-char hex or string
 const mod = new HyperP2PStreamBackpressure({ topic, enableBackgroundTimers: false })
 await mod.ready()   // joins swarm when topic set
 // ... application logic ...
 await mod.close()
 ```
-`modules/messaging-streams/hyper-p2p-stream-backpressure/`
+## Docs
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+- [docs/api.md](docs/api.md) — constructor, methods, events, errors
 - [docs/architecture.md](docs/architecture.md) — wire types, state, composition
 - [../../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
 - [../../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
 ## Test
 ```bash
 npm install && npm test
 ```
@@ -1,23 +1,92 @@
-# hyper-p2p-stream-backpressure API
+# API: hyper-p2p-stream-backpressure
-**Status:** scaffold · **Protocol:** `stream-backpressure/v1`
+**Protocol:** `stream-backpressure/v1`
-## Class `HyperP2PStreamBackpressure`
+**Export:** `HyperP2PStreamBackpressure`
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+## Overview
-### `constructor(opts?)`
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-### `getStats()`
+## Constructor
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+```js
 const mod = new HyperP2PStreamBackpressure(opts)
 ```
-### `ready()`
+| Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
 | `keyPair` | KeyPair | random | Ed25519 key pair |
 | `highWaterMark` | number | 65536 | highWaterMark |
-Resolves immediately (no-op).
+## Methods
-## Wire (planned)
+### `write(chunk)`
-| Message | Direction | Notes |
+- **Returns:** `value`
-|---------|-----------|-------|
+- **Throws:**
-| TBD | gossip | Defined in implementation pass |
+  - `Error: chunk required`
 ### `pause(—)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `resume(—)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `read(—)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `pending(—)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getStats(—)`
 - **Returns:** `object`
 - **Throws:** — (none documented in method body)
 ### `ready(—)`
 - **Returns:** `Promise`
 - **Throws:** — (none documented in method body)
 ### `close(—)`
 - **Returns:** `Promise<void>`
 - **Throws:** — (none documented in method body)
 ## Events
 | Event | Payload |
 |-------|---------|
 | `backpressure` | bytes |
 | `data` | buf |
 | `pause` | no payload |
 | `resume` | no payload |
 ## getStats()
 Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
 Library-only modules may include `mode: 'local'`.
 ## Errors
 Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 ## P2P
 When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `stream-backpressure/v1`.
 ## Testing
 ```bash
 npm install && npm test
 ```
@@ -1,15 +1,27 @@
-# hyper-p2p-stream-backpressure architecture
+# Architecture: hyper-p2p-stream-backpressure
-**Tier:** scaffold · **Category:** `messaging-streams`
+**Category:** General
-## Role
+```mermaid
 flowchart LR
  App[Application] --> Mod[HyperP2PStreamBackpressure]
  Mod --> Mux[Protomux stream-backpressure/v1]
  Mux --> Swarm[Hyperswarm]
 ```
-Backpressure for P2P streams.
+## Wire messages
 | type | fields | direction | behavior |
 |------|--------|-----------|----------|
 | *(local only)* | — | — | No gossip wire types |
 ## State model
 - In-memory `Map` / `Set` structures for hot path
 - Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
 - `close()` tears down swarm, timers, and clears ephemeral state
 ## Composition
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
+Composes with: see MODULE_CATEGORIES.md.
 ## Holepunch boundary
 Inspiration: n/a
@@ -3,3 +3,7 @@
 ## [0.0.0-scaffold] — Wave 8
 - Registry scaffold: file tree, load smoke tests, docs stubs
 ## [0.3.2] - 2026-05-21
 ### Changed
 - Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
@@ -1,28 +1,41 @@
 # hyper-p2p-stream-chunker
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `stream-chunker/v1` · **Wave:** 8
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-Chunked stream framing.
+**Category:** General
-## Holepunch references (inspiration only)
+**Composes with:** 
- `hyperbeam`
+**Protocol:** `stream-chunker/v1`
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+## When to use
-## Composes with
+Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-multipath-fanout`
+## When not to use
-## Planned API
+Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair
+## Quick start
 - `getStats()` — scaffold counters
 - `ready()` — no-op until implemented
 - Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
-## Layout
+```js
 const { HyperP2PStreamChunker } = require('hyper-p2p-stream-chunker')
 const topic = process.argv[2] // 64-char hex or string
 const mod = new HyperP2PStreamChunker({ topic, enableBackgroundTimers: false })
 await mod.ready()   // joins swarm when topic set
 // ... application logic ...
 await mod.close()
 ```
-`modules/messaging-streams/hyper-p2p-stream-chunker/`
+## Docs
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+- [docs/api.md](docs/api.md) — constructor, methods, events, errors
 - [docs/architecture.md](docs/architecture.md) — wire types, state, composition
 - [../../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
 - [../../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
 ## Test
 ```bash
 npm install && npm test
 ```
@@ -1,23 +1,73 @@
-# hyper-p2p-stream-chunker API
+# API: hyper-p2p-stream-chunker
-**Status:** scaffold · **Protocol:** `stream-chunker/v1`
+**Protocol:** `stream-chunker/v1`
-## Class `HyperP2PStreamChunker`
+**Export:** `HyperP2PStreamChunker`
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+## Overview
-### `constructor(opts?)`
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-### `getStats()`
+## Constructor
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+```js
 const mod = new HyperP2PStreamChunker(opts)
 ```
-### `ready()`
+| Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
 | `keyPair` | KeyPair | random | Ed25519 key pair |
 | `chunkSize` | number | 4096 | chunkSize |
-Resolves immediately (no-op).
+## Methods
-## Wire (planned)
+### `push(data)`
-| Message | Direction | Notes |
+- **Returns:** `value`
-|---------|-----------|-------|
+- **Throws:** — (none documented in method body)
-| TBD | gossip | Defined in implementation pass |
+
 ### `flush(—)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getStats(—)`
 - **Returns:** `object`
 - **Throws:** — (none documented in method body)
 ### `ready(—)`
 - **Returns:** `Promise`
 - **Throws:** — (none documented in method body)
 ### `close(—)`
 - **Returns:** `Promise<void>`
 - **Throws:** — (none documented in method body)
 ## Events
 | Event | Payload |
 |-------|---------|
 | `chunk` | tail |
 ## getStats()
 Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
 Library-only modules may include `mode: 'local'`.
 ## Errors
 Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 ## P2P
 When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `stream-chunker/v1`.
 ## Testing
 ```bash
 npm install && npm test
 ```
@@ -1,15 +1,27 @@
-# hyper-p2p-stream-chunker architecture
+# Architecture: hyper-p2p-stream-chunker
-**Tier:** scaffold · **Category:** `messaging-streams`
+**Category:** General
-## Role
+```mermaid
 flowchart LR
  App[Application] --> Mod[HyperP2PStreamChunker]
  Mod --> Mux[Protomux stream-chunker/v1]
  Mux --> Swarm[Hyperswarm]
 ```
-Chunked stream framing.
+## Wire messages
 | type | fields | direction | behavior |
 |------|--------|-----------|----------|
 | *(local only)* | — | — | No gossip wire types |
 ## State model
 - In-memory `Map` / `Set` structures for hot path
 - Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
 - `close()` tears down swarm, timers, and clears ephemeral state
 ## Composition
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
+Composes with: see MODULE_CATEGORIES.md.
 ## Holepunch boundary
 Inspiration: n/a
@@ -3,3 +3,7 @@
 ## [0.0.0-scaffold] — Wave 8
 - Registry scaffold: file tree, load smoke tests, docs stubs
 ## [0.3.2] - 2026-05-21
 ### Changed
 - Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
@@ -1,28 +1,43 @@
 # hyper-p2p-stream-multiplex
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `stream-multiplex/v1` · **Wave:** 8
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-Stream multiplex over mux.
+**Category:** General
-## Holepunch references (inspiration only)
+**Composes with:** 
- `protomux`
+**Protocol:** `stream-multiplex/v1`
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+## When to use
-## Composes with
+Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-rpc`
+## When not to use
-## Planned API
+Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair
+## Quick start
 - `getStats()` — scaffold counters
 - `ready()` — no-op until implemented
 - Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
-## Layout
+```js
 const { StreamHandle } = require('hyper-p2p-stream-multiplex')
 const topic = process.argv[2] // 64-char hex or string
 const mod = new StreamHandle({ topic, enableBackgroundTimers: false })
 await mod.ready()   // joins swarm when topic set
 // ... application logic ...
 await mod.close()
 ```
-`modules/messaging-streams/hyper-p2p-stream-multiplex/`
+## Docs
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+- [docs/api.md](docs/api.md) — constructor, methods, events, errors
 - [docs/architecture.md](docs/architecture.md) — wire types, state, composition
 - [../../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
 - [../../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
 - Integration: [`../../real_tests/integration/`](../../real_tests/integration/) — `stream-multiplex-two-node.js`
 ## Test
 ```bash
 npm install && npm test
 ```
@@ -1,23 +1,99 @@
-# hyper-p2p-stream-multiplex API
+# API: hyper-p2p-stream-multiplex
-**Status:** scaffold · **Protocol:** `stream-multiplex/v1`
+**Protocol:** `stream-multiplex/v1`
-## Class `HyperP2PStreamMultiplex`
+**Export:** `StreamHandle`
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+## Overview
-### `constructor(opts?)`
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-### `getStats()`
+## Constructor
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+```js
 const mod = new StreamHandle(opts)
 ```
-### `ready()`
+| Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
 | `keyPair` | KeyPair | random | Ed25519 key pair |
 | `highWaterMark` | number | 65536 | highWaterMark |
-Resolves immediately (no-op).
+## Methods
-## Wire (planned)
+### `write(chunk)`
-| Message | Direction | Notes |
+- **Returns:** `value`
-|---------|-----------|-------|
+- **Throws:**
-| TBD | gossip | Defined in implementation pass |
+  - `Error: stream closed`
 ### `end(chunk)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `ondata(fn)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `openStream(id = null)`
 - **Returns:** `value`
 - **Throws:**
  - `Error: stream id already open`
 ### `receiveFrame(frame)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `closeStream(streamId)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getStats(—)`
 - **Returns:** `object`
 - **Throws:** — (none documented in method body)
 ### `ready(—)`
 - **Returns:** `Promise`
 - **Throws:** — (none documented in method body)
 ### `close(—)`
 - **Returns:** `Promise<void>`
 - **Throws:** — (none documented in method body)
 ## Events
 | Event | Payload |
 |-------|---------|
 | `closed` | no payload |
 | `frame` | frame |
 | `open` | streamId |
 ## getStats()
 Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
 Library-only modules may include `mode: 'local'`.
 ## Errors
 Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 ## P2P
 When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `stream-multiplex/v1`.
 ## Testing
 ```bash
 npm install && npm test
 ```
 Integration: [`../../../real_tests/integration/stream-multiplex-two-node.js`](../../../real_tests/integration/stream-multiplex-two-node.js)
@@ -1,15 +1,43 @@
-# hyper-p2p-stream-multiplex architecture
+# Architecture: hyper-p2p-stream-multiplex
-**Tier:** scaffold · **Category:** `messaging-streams`
+**Category:** General
-## Role
+```mermaid
 flowchart LR
  App[Application] --> Mod[StreamHandle]
  Mod --> Mux[Protomux stream-multiplex/v1]
  Mux --> Swarm[Hyperswarm]
 ```
-Stream multiplex over mux.
+## Sequence (P2P)
 ```mermaid
 sequenceDiagram
  participant App
  participant Mod as Module
  participant SW as Hyperswarm
  participant Peer
  App->>Mod: ready(topic)
  Mod->>SW: join(topic)
  SW->>Peer: connection
  Mod->>Peer: gossip / Protomux
  Peer-->>Mod: onmessage
  Mod-->>App: emit(event)
 ```
 ## Wire messages
 | type | fields | direction | behavior |
 |------|--------|-----------|----------|
 | `frame` | fin, type | gossip | Handled in onmessage / gossipSend |
 ## State model
 - In-memory `Map` / `Set` structures for hot path
 - Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
 - `close()` tears down swarm, timers, and clears ephemeral state
 ## Composition
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
+Composes with: see MODULE_CATEGORIES.md.
 ## Holepunch boundary
 Inspiration: n/a
@@ -3,3 +3,7 @@
 ## [0.0.0-scaffold] — Wave 8
 - Registry scaffold: file tree, load smoke tests, docs stubs
 ## [0.3.2] - 2026-05-21
 ### Changed
 - Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
@@ -1,28 +1,41 @@
 # hyper-p2p-stream-resume-token
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `stream-resume-token/v1` · **Wave:** 8
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-Resume tokens for streams.
+**Category:** General
-## Holepunch references (inspiration only)
+**Composes with:** 
- `hypercore-byte-stream`
+**Protocol:** `stream-resume-token/v1`
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+## When to use
-## Composes with
+Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-session-bridge`
+## When not to use
-## Planned API
+Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair
+## Quick start
 - `getStats()` — scaffold counters
 - `ready()` — no-op until implemented
 - Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
-## Layout
+```js
 const { HyperP2PStreamResumeToken } = require('hyper-p2p-stream-resume-token')
 const topic = process.argv[2] // 64-char hex or string
 const mod = new HyperP2PStreamResumeToken({ topic, enableBackgroundTimers: false })
 await mod.ready()   // joins swarm when topic set
 // ... application logic ...
 await mod.close()
 ```
-`modules/messaging-streams/hyper-p2p-stream-resume-token/`
+## Docs
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+- [docs/api.md](docs/api.md) — constructor, methods, events, errors
 - [docs/architecture.md](docs/architecture.md) — wire types, state, composition
 - [../../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
 - [../../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
 ## Test
 ```bash
 npm install && npm test
 ```
@@ -1,23 +1,86 @@
-# hyper-p2p-stream-resume-token API
+# API: hyper-p2p-stream-resume-token
-**Status:** scaffold · **Protocol:** `stream-resume-token/v1`
+**Protocol:** `stream-resume-token/v1`
-## Class `HyperP2PStreamResumeToken`
+**Export:** `HyperP2PStreamResumeToken`
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+## Overview
-### `constructor(opts?)`
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-### `getStats()`
+## Constructor
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+```js
 const mod = new HyperP2PStreamResumeToken(opts)
 ```
-### `ready()`
+| Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
 | `keyPair` | KeyPair | random | Ed25519 key pair |
-Resolves immediately (no-op).
+## Methods
-## Wire (planned)
+### `write(chunk)`
-| Message | Direction | Notes |
+- **Returns:** `value`
-|---------|-----------|-------|
+- **Throws:**
-| TBD | gossip | Defined in implementation pass |
+  - `Error: chunk required`
 ### `checkpoint(—)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `resume(tokenId)`
 - **Returns:** `value`
 - **Throws:**
  - `Error: unknown resume token`
 ### `readFromOffset(—)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getStats(—)`
 - **Returns:** `object`
 - **Throws:** — (none documented in method body)
 ### `ready(—)`
 - **Returns:** `Promise`
 - **Throws:** — (none documented in method body)
 ### `close(—)`
 - **Returns:** `Promise<void>`
 - **Throws:** — (none documented in method body)
 ## Events
 | Event | Payload |
 |-------|---------|
 | `checkpoint` | token |
 | `data` | buf |
 | `resume` | token |
 ## getStats()
 Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
 Library-only modules may include `mode: 'local'`.
 ## Errors
 Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 ## P2P
 When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `stream-resume-token/v1`.
 ## Testing
 ```bash
 npm install && npm test
 ```
@@ -1,15 +1,27 @@
-# hyper-p2p-stream-resume-token architecture
+# Architecture: hyper-p2p-stream-resume-token
-**Tier:** scaffold · **Category:** `messaging-streams`
+**Category:** General
-## Role
+```mermaid
 flowchart LR
  App[Application] --> Mod[HyperP2PStreamResumeToken]
  Mod --> Mux[Protomux stream-resume-token/v1]
  Mux --> Swarm[Hyperswarm]
 ```
-Resume tokens for streams.
+## Wire messages
 | type | fields | direction | behavior |
 |------|--------|-----------|----------|
 | *(local only)* | — | — | No gossip wire types |
 ## State model
 - In-memory `Map` / `Set` structures for hot path
 - Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
 - `close()` tears down swarm, timers, and clears ephemeral state
 ## Composition
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
+Composes with: see MODULE_CATEGORIES.md.
 ## Holepunch boundary
 Inspiration: n/a
@@ -3,3 +3,7 @@
 ## [0.0.0-scaffold] — Wave 8
 - Registry scaffold: file tree, load smoke tests, docs stubs
 ## [0.3.2] - 2026-05-21
 ### Changed
 - Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
@@ -1,28 +1,41 @@
 # hyper-p2p-stream-tee
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `stream-tee/v1` · **Wave:** 8
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-Stream tee fan-out.
+**Category:** General
-## Holepunch references (inspiration only)
+**Composes with:** 
- `protomux`
+**Protocol:** `stream-tee/v1`
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+## When to use
-## Composes with
+Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-distributed-event-bus`
+## When not to use
-## Planned API
+Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair
+## Quick start
 - `getStats()` — scaffold counters
 - `ready()` — no-op until implemented
 - Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
-## Layout
+```js
 const { HyperP2PStreamTee } = require('hyper-p2p-stream-tee')
 const topic = process.argv[2] // 64-char hex or string
 const mod = new HyperP2PStreamTee({ topic, enableBackgroundTimers: false })
 await mod.ready()   // joins swarm when topic set
 // ... application logic ...
 await mod.close()
 ```
-`modules/messaging-streams/hyper-p2p-stream-tee/`
+## Docs
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+- [docs/api.md](docs/api.md) — constructor, methods, events, errors
 - [docs/architecture.md](docs/architecture.md) — wire types, state, composition
 - [../../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
 - [../../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
 ## Test
 ```bash
 npm install && npm test
 ```
@@ -1,23 +1,84 @@
-# hyper-p2p-stream-tee API
+# API: hyper-p2p-stream-tee
-**Status:** scaffold · **Protocol:** `stream-tee/v1`
+**Protocol:** `stream-tee/v1`
-## Class `HyperP2PStreamTee`
+**Export:** `HyperP2PStreamTee`
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+## Overview
-### `constructor(opts?)`
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-### `getStats()`
+## Constructor
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+```js
 const mod = new HyperP2PStreamTee(opts)
 ```
-### `ready()`
+| Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
 | `keyPair` | KeyPair | random | Ed25519 key pair |
-Resolves immediately (no-op).
+## Methods
-## Wire (planned)
+### `addBranch(name)`
-| Message | Direction | Notes |
+- **Returns:** `value`
-|---------|-----------|-------|
+- **Throws:**
-| TBD | gossip | Defined in implementation pass |
+  - `Error: branch name required`
 ### `write(chunk)`
 - **Returns:** `value`
 - **Throws:**
  - `Error: chunk required`
 ### `readBranch(name)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `pending(name)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getStats(—)`
 - **Returns:** `object`
 - **Throws:** — (none documented in method body)
 ### `ready(—)`
 - **Returns:** `Promise`
 - **Throws:** — (none documented in method body)
 ### `close(—)`
 - **Returns:** `Promise<void>`
 - **Throws:** — (none documented in method body)
 ## Events
 | Event | Payload |
 |-------|---------|
 | `data` | buf |
 ## getStats()
 Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
 Library-only modules may include `mode: 'local'`.
 ## Errors
 Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 ## P2P
 When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `stream-tee/v1`.
 ## Testing
 ```bash
 npm install && npm test
 ```
@@ -1,15 +1,27 @@
-# hyper-p2p-stream-tee architecture
+# Architecture: hyper-p2p-stream-tee
-**Tier:** scaffold · **Category:** `messaging-streams`
+**Category:** General
-## Role
+```mermaid
 flowchart LR
  App[Application] --> Mod[HyperP2PStreamTee]
  Mod --> Mux[Protomux stream-tee/v1]
  Mux --> Swarm[Hyperswarm]
 ```
-Stream tee fan-out.
+## Wire messages
 | type | fields | direction | behavior |
 |------|--------|-----------|----------|
 | *(local only)* | — | — | No gossip wire types |
 ## State model
 - In-memory `Map` / `Set` structures for hot path
 - Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
 - `close()` tears down swarm, timers, and clears ephemeral state
 ## Composition
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
+Composes with: see MODULE_CATEGORIES.md.
 ## Holepunch boundary
 Inspiration: n/a
@@ -3,3 +3,7 @@
 ## [0.0.0-scaffold] — Wave 8
 - Registry scaffold: file tree, load smoke tests, docs stubs
 ## [0.3.2] - 2026-05-21
 ### Changed
 - Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
@@ -1,28 +1,41 @@
 # hyper-p2p-stream-transform
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `stream-transform/v1` · **Wave:** 8
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-Transform pipeline for streams.
+**Category:** General
-## Holepunch references (inspiration only)
+**Composes with:** 
- `protomux`
+**Protocol:** `stream-transform/v1`
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+## When to use
-## Composes with
+Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-pattern-router`
+## When not to use
-## Planned API
+Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair
+## Quick start
 - `getStats()` — scaffold counters
 - `ready()` — no-op until implemented
 - Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
-## Layout
+```js
 const { HyperP2PStreamTransform } = require('hyper-p2p-stream-transform')
 const topic = process.argv[2] // 64-char hex or string
 const mod = new HyperP2PStreamTransform({ topic, enableBackgroundTimers: false })
 await mod.ready()   // joins swarm when topic set
 // ... application logic ...
 await mod.close()
 ```
-`modules/messaging-streams/hyper-p2p-stream-transform/`
+## Docs
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+- [docs/api.md](docs/api.md) — constructor, methods, events, errors
 - [docs/architecture.md](docs/architecture.md) — wire types, state, composition
 - [../../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
 - [../../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
 ## Test
 ```bash
 npm install && npm test
 ```
@@ -1,23 +1,84 @@
-# hyper-p2p-stream-transform API
+# API: hyper-p2p-stream-transform
-**Status:** scaffold · **Protocol:** `stream-transform/v1`
+**Protocol:** `stream-transform/v1`
-## Class `HyperP2PStreamTransform`
+**Export:** `HyperP2PStreamTransform`
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+## Overview
-### `constructor(opts?)`
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-### `getStats()`
+## Constructor
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+```js
 const mod = new HyperP2PStreamTransform(opts)
 ```
-### `ready()`
+| Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
 | `keyPair` | KeyPair | random | Ed25519 key pair |
-Resolves immediately (no-op).
+## Methods
-## Wire (planned)
+### `setTransform(fn)`
-| Message | Direction | Notes |
+- **Returns:** `value`
-|---------|-----------|-------|
+- **Throws:**
-| TBD | gossip | Defined in implementation pass |
+  - `Error: transform must be a function`
 ### `write(chunk)`
 - **Returns:** `value`
 - **Throws:**
  - `Error: chunk required`
 ### `read(—)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `pending(—)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getStats(—)`
 - **Returns:** `object`
 - **Throws:** — (none documented in method body)
 ### `ready(—)`
 - **Returns:** `Promise`
 - **Throws:** — (none documented in method body)
 ### `close(—)`
 - **Returns:** `Promise<void>`
 - **Throws:** — (none documented in method body)
 ## Events
 | Event | Payload |
 |-------|---------|
 | `data` | out |
 ## getStats()
 Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
 Library-only modules may include `mode: 'local'`.
 ## Errors
 Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 ## P2P
 When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `stream-transform/v1`.
 ## Testing
 ```bash
 npm install && npm test
 ```
@@ -1,15 +1,27 @@
-# hyper-p2p-stream-transform architecture
+# Architecture: hyper-p2p-stream-transform
-**Tier:** scaffold · **Category:** `messaging-streams`
+**Category:** General
-## Role
+```mermaid
 flowchart LR
  App[Application] --> Mod[HyperP2PStreamTransform]
  Mod --> Mux[Protomux stream-transform/v1]
  Mux --> Swarm[Hyperswarm]
 ```
-Transform pipeline for streams.
+## Wire messages
 | type | fields | direction | behavior |
 |------|--------|-----------|----------|
 | *(local only)* | — | — | No gossip wire types |
 ## State model
 - In-memory `Map` / `Set` structures for hot path
 - Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
 - `close()` tears down swarm, timers, and clears ephemeral state
 ## Composition
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
+Composes with: see MODULE_CATEGORIES.md.
 ## Holepunch boundary
 Inspiration: n/a
@@ -3,3 +3,7 @@
 ## [0.0.0-scaffold] — Wave 8
 - Registry scaffold: file tree, load smoke tests, docs stubs
 ## [0.3.2] - 2026-05-21
 ### Changed
 - Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
@@ -1,28 +1,41 @@
 # hyper-p2p-health-probe
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `health-probe/v1` · **Wave:** 8
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-Health probe protocol.
+**Category:** General
-## Holepunch references (inspiration only)
+**Composes with:** 
- `hyper-health-check`
+**Protocol:** `health-probe/v1`
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+## When to use
-## Composes with
+Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-presence`
+## When not to use
-## Planned API
+Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair
+## Quick start
 - `getStats()` — scaffold counters
 - `ready()` — no-op until implemented
 - Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
-## Layout
+```js
 const { HyperP2PHealthProbe } = require('hyper-p2p-health-probe')
 const topic = process.argv[2] // 64-char hex or string
 const mod = new HyperP2PHealthProbe({ topic, enableBackgroundTimers: false })
 await mod.ready()   // joins swarm when topic set
 // ... application logic ...
 await mod.close()
 ```
-`modules/observability/hyper-p2p-health-probe/`
+## Docs
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+- [docs/api.md](docs/api.md) — constructor, methods, events, errors
 - [docs/architecture.md](docs/architecture.md) — wire types, state, composition
 - [../../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
 - [../../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
 ## Test
 ```bash
 npm install && npm test
 ```
@@ -1,23 +1,78 @@
-# hyper-p2p-health-probe API
+# API: hyper-p2p-health-probe
-**Status:** scaffold · **Protocol:** `health-probe/v1`
+**Protocol:** `health-probe/v1`
-## Class `HyperP2PHealthProbe`
+**Export:** `HyperP2PHealthProbe`
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+## Overview
-### `constructor(opts?)`
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-### `getStats()`
+## Constructor
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+```js
 const mod = new HyperP2PHealthProbe(opts)
 ```
-### `ready()`
+| Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `topic` | varies | null | topic |
 | `keyPair` | KeyPair | random Ed25519 | keyPair |
-Resolves immediately (no-op).
+## Methods
-## Wire (planned)
+### `report(peerId, status = {})`
-| Message | Direction | Notes |
+- **Returns:** `value`
-|---------|-----------|-------|
+- **Throws:** — (none documented in method body)
-| TBD | gossip | Defined in implementation pass |
+
 ### `get(peerId)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `healthyPeers(—)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getStats(—)`
 - **Returns:** `object`
 - **Throws:** — (none documented in method body)
 ### `ready(—)`
 - **Returns:** `Promise`
 - **Throws:** — (none documented in method body)
 ### `close(—)`
 - **Returns:** `Promise<void>`
 - **Throws:** — (none documented in method body)
 ## Events
 | Event | Payload |
 |-------|---------|
 | `remote-report` | data.entry |
 | `report` | entry |
 ## getStats()
 Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
 Library-only modules may include `mode: 'local'`.
 ## Errors
 Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 ## P2P
 When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `health-probe/v1`.
 ## Testing
 ```bash
 npm install && npm test
 ```
@@ -1,15 +1,43 @@
-# hyper-p2p-health-probe architecture
+# Architecture: hyper-p2p-health-probe
-**Tier:** scaffold · **Category:** `observability`
+**Category:** General
-## Role
+```mermaid
 flowchart LR
  App[Application] --> Mod[HyperP2PHealthProbe]
  Mod --> Mux[Protomux health-probe/v1]
  Mux --> Swarm[Hyperswarm]
 ```
-Health probe protocol.
+## Sequence (P2P)
 ```mermaid
 sequenceDiagram
  participant App
  participant Mod as Module
  participant SW as Hyperswarm
  participant Peer
  App->>Mod: ready(topic)
  Mod->>SW: join(topic)
  SW->>Peer: connection
  Mod->>Peer: gossip / Protomux
  Peer-->>Mod: onmessage
  Mod-->>App: emit(event)
 ```
 ## Wire messages
 | type | fields | direction | behavior |
 |------|--------|-----------|----------|
 | `health` | type | gossip | Handled in onmessage / gossipSend |
 ## State model
 - In-memory `Map` / `Set` structures for hot path
 - Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
 - `close()` tears down swarm, timers, and clears ephemeral state
 ## Composition
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
+Composes with: see MODULE_CATEGORIES.md.
 ## Holepunch boundary
 Inspiration: n/a
@@ -3,6 +3,8 @@ const { HyperP2PHealthProbe } = require('../index.js')
 async function main () {
  const m = new HyperP2PHealthProbe()
-  console.log('[scaffold]', m.getStats())
+  m.report('peer-1', { ok: true, rttMs: 8 })
  console.log('[health-probe]', m.getStats())
  await m.close()
 }
 main().catch(console.error)
@@ -3,3 +3,7 @@
 ## [0.0.0-scaffold] — Wave 8
 - Registry scaffold: file tree, load smoke tests, docs stubs
 ## [0.3.2] - 2026-05-21
 ### Changed
 - Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
@@ -1,28 +1,41 @@
 # hyper-p2p-log-gossip
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `log-gossip/v1` · **Wave:** 8
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-Structured log gossip.
+**Category:** General
-## Holepunch references (inspiration only)
+**Composes with:** 
- `hypercore-logger`
+**Protocol:** `log-gossip/v1`
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+## When to use
-## Composes with
+Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-gossip-mesh`
+## When not to use
-## Planned API
+Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair
+## Quick start
 - `getStats()` — scaffold counters
 - `ready()` — no-op until implemented
 - Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
-## Layout
+```js
 const { HyperP2PLogGossip } = require('hyper-p2p-log-gossip')
 const topic = process.argv[2] // 64-char hex or string
 const mod = new HyperP2PLogGossip({ topic, enableBackgroundTimers: false })
 await mod.ready()   // joins swarm when topic set
 // ... application logic ...
 await mod.close()
 ```
-`modules/observability/hyper-p2p-log-gossip/`
+## Docs
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+- [docs/api.md](docs/api.md) — constructor, methods, events, errors
 - [docs/architecture.md](docs/architecture.md) — wire types, state, composition
 - [../../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
 - [../../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
 ## Test
 ```bash
 npm install && npm test
 ```
@@ -1,23 +1,75 @@
-# hyper-p2p-log-gossip API
+# API: hyper-p2p-log-gossip
-**Status:** scaffold · **Protocol:** `log-gossip/v1`
+**Protocol:** `log-gossip/v1`
-## Class `HyperP2PLogGossip`
+**Export:** `HyperP2PLogGossip`
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+## Overview
-### `constructor(opts?)`
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-### `getStats()`
+## Constructor
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+```js
 const mod = new HyperP2PLogGossip(opts)
 ```
-### `ready()`
+| Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `topic` | varies | null | topic |
 | `keyPair` | KeyPair | random Ed25519 | keyPair |
 | `maxEntries` | number | 500 | maxEntries |
 | `minLevel` | varies | 'debug' | minLevel |
-Resolves immediately (no-op).
+## Methods
-## Wire (planned)
+### `log(level, message, meta = {})`
-| Message | Direction | Notes |
+- **Returns:** `value`
-|---------|-----------|-------|
+- **Throws:** — (none documented in method body)
-| TBD | gossip | Defined in implementation pass |
+
 ### `tail(limit = 50)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getStats(—)`
 - **Returns:** `object`
 - **Throws:** — (none documented in method body)
 ### `ready(—)`
 - **Returns:** `Promise`
 - **Throws:** — (none documented in method body)
 ### `close(—)`
 - **Returns:** `Promise<void>`
 - **Throws:** — (none documented in method body)
 ## Events
 | Event | Payload |
 |-------|---------|
 | `log` | entry |
 | `remote-log` | data.entry |
 ## getStats()
 Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
 Library-only modules may include `mode: 'local'`.
 ## Errors
 Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 ## P2P
 When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `log-gossip/v1`.
 ## Testing
 ```bash
 npm install && npm test
 ```
@@ -1,15 +1,43 @@
-# hyper-p2p-log-gossip architecture
+# Architecture: hyper-p2p-log-gossip
-**Tier:** scaffold · **Category:** `observability`
+**Category:** General
-## Role
+```mermaid
 flowchart LR
  App[Application] --> Mod[HyperP2PLogGossip]
  Mod --> Mux[Protomux log-gossip/v1]
  Mux --> Swarm[Hyperswarm]
 ```
-Structured log gossip.
+## Sequence (P2P)
 ```mermaid
 sequenceDiagram
  participant App
  participant Mod as Module
  participant SW as Hyperswarm
  participant Peer
  App->>Mod: ready(topic)
  Mod->>SW: join(topic)
  SW->>Peer: connection
  Mod->>Peer: gossip / Protomux
  Peer-->>Mod: onmessage
  Mod-->>App: emit(event)
 ```
 ## Wire messages
 | type | fields | direction | behavior |
 |------|--------|-----------|----------|
 | `log` | type | gossip | Handled in onmessage / gossipSend |
 ## State model
 - In-memory `Map` / `Set` structures for hot path
 - Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
 - `close()` tears down swarm, timers, and clears ephemeral state
 ## Composition
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
+Composes with: see MODULE_CATEGORIES.md.
 ## Holepunch boundary
 Inspiration: n/a
@@ -3,6 +3,8 @@ const { HyperP2PLogGossip } = require('../index.js')
 async function main () {
  const m = new HyperP2PLogGossip()
-  console.log('[scaffold]', m.getStats())
+  m.log('info', 'example started')
  console.log('[log-gossip]', m.tail(1))
  await m.close()
 }
 main().catch(console.error)
@@ -3,3 +3,7 @@
 ## [0.0.0-scaffold] — Wave 8
 - Registry scaffold: file tree, load smoke tests, docs stubs
 ## [0.3.2] - 2026-05-21
 ### Changed
 - Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
@@ -1,28 +1,41 @@
 # hyper-p2p-metrics-aggregator
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `metrics-aggregator/v1` · **Wave:** 8
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-Metrics aggregation gossip.
+**Category:** General
-## Holepunch references (inspiration only)
+**Composes with:** 
- `hyper-instrument`
+**Protocol:** `metrics-aggregator/v1`
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+## When to use
-## Composes with
+Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-congestion-signal`
+## When not to use
-## Planned API
+Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair
+## Quick start
 - `getStats()` — scaffold counters
 - `ready()` — no-op until implemented
 - Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
-## Layout
+```js
 const { HyperP2PMetricsAggregator } = require('hyper-p2p-metrics-aggregator')
 const topic = process.argv[2] // 64-char hex or string
 const mod = new HyperP2PMetricsAggregator({ topic, enableBackgroundTimers: false })
 await mod.ready()   // joins swarm when topic set
 // ... application logic ...
 await mod.close()
 ```
-`modules/observability/hyper-p2p-metrics-aggregator/`
+## Docs
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+- [docs/api.md](docs/api.md) — constructor, methods, events, errors
 - [docs/architecture.md](docs/architecture.md) — wire types, state, composition
 - [../../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
 - [../../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
 ## Test
 ```bash
 npm install && npm test
 ```
@@ -1,23 +1,83 @@
-# hyper-p2p-metrics-aggregator API
+# API: hyper-p2p-metrics-aggregator
-**Status:** scaffold · **Protocol:** `metrics-aggregator/v1`
+**Protocol:** `metrics-aggregator/v1`
-## Class `HyperP2PMetricsAggregator`
+**Export:** `HyperP2PMetricsAggregator`
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+## Overview
-### `constructor(opts?)`
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-### `getStats()`
+## Constructor
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+```js
 const mod = new HyperP2PMetricsAggregator(opts)
 ```
-### `ready()`
+| Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `topic` | varies | null | topic |
 | `keyPair` | KeyPair | random Ed25519 | keyPair |
-Resolves immediately (no-op).
+## Methods
-## Wire (planned)
+### `record(name, value, labels = {})`
-| Message | Direction | Notes |
+- **Returns:** `value`
-|---------|-----------|-------|
+- **Throws:**
-| TBD | gossip | Defined in implementation pass |
+  - `Error: metric name required`
  - `Error: value must be a number`
 ### `summarize(name, labels = {})`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `mergeRemote(name, value, labels = {})`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `exportAll(—)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getStats(—)`
 - **Returns:** `object`
 - **Throws:** — (none documented in method body)
 ### `ready(—)`
 - **Returns:** `Promise`
 - **Throws:** — (none documented in method body)
 ### `close(—)`
 - **Returns:** `Promise<void>`
 - **Throws:** — (none documented in method body)
 ## Events
 | Event | Payload |
 |-------|---------|
 ## getStats()
 Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
 Library-only modules may include `mode: 'local'`.
 ## Errors
 Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 ## P2P
 When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `metrics-aggregator/v1`.
 ## Testing
 ```bash
 npm install && npm test
 ```
@@ -1,15 +1,43 @@
-# hyper-p2p-metrics-aggregator architecture
+# Architecture: hyper-p2p-metrics-aggregator
-**Tier:** scaffold · **Category:** `observability`
+**Category:** General
-## Role
+```mermaid
 flowchart LR
  App[Application] --> Mod[HyperP2PMetricsAggregator]
  Mod --> Mux[Protomux metrics-aggregator/v1]
  Mux --> Swarm[Hyperswarm]
 ```
-Metrics aggregation gossip.
+## Sequence (P2P)
 ```mermaid
 sequenceDiagram
  participant App
  participant Mod as Module
  participant SW as Hyperswarm
  participant Peer
  App->>Mod: ready(topic)
  Mod->>SW: join(topic)
  SW->>Peer: connection
  Mod->>Peer: gossip / Protomux
  Peer-->>Mod: onmessage
  Mod-->>App: emit(event)
 ```
 ## Wire messages
 | type | fields | direction | behavior |
 |------|--------|-----------|----------|
 | `metric` | at, type | gossip | Handled in onmessage / gossipSend |
 ## State model
 - In-memory `Map` / `Set` structures for hot path
 - Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
 - `close()` tears down swarm, timers, and clears ephemeral state
 ## Composition
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
+Composes with: see MODULE_CATEGORIES.md.
 ## Holepunch boundary
 Inspiration: n/a
@@ -3,6 +3,8 @@ const { HyperP2PMetricsAggregator } = require('../index.js')
 async function main () {
  const m = new HyperP2PMetricsAggregator()
-  console.log('[scaffold]', m.getStats())
+  m.record('latency_ms', 42)
  console.log('[metrics]', m.summarize('latency_ms'))
  await m.close()
 }
 main().catch(console.error)
@@ -3,3 +3,7 @@
 ## [0.0.0-scaffold] — Wave 8
 - Registry scaffold: file tree, load smoke tests, docs stubs
 ## [0.3.2] - 2026-05-21
 ### Changed
 - Exhaustive documentation pass (api, architecture, README) per DOC_STANDARDS.md.
@@ -1,28 +1,41 @@
 # hyper-p2p-stats-exporter
-**Status:** scaffold (`0.0.0-scaffold`) · **Protocol:** `stats-exporter/v1` · **Wave:** 8
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-Stats export format.
+**Category:** General
-## Holepunch references (inspiration only)
+**Composes with:** 
- `hypercore-stats`
+**Protocol:** `stats-exporter/v1`
-> This module composes on Hyperswarm/Hypercore — it does **not** re-implement upstream packages.
+## When to use
-## Composes with
+Multi-peer apps that need general over a shared Hyperswarm topic.
- `hyper-p2p-metrics-aggregator`
+## When not to use
-## Planned API
+Single-process tools with no P2P topic (use local APIs only or skip `ready()`).
- `constructor(opts)` — topic, optional keyPair
+## Quick start
 - `getStats()` — scaffold counters
 - `ready()` — no-op until implemented
 - Domain methods — throw `not implemented: scaffold` until Wave 8+ pass
-## Layout
+```js
 const { HyperP2PStatsExporter } = require('hyper-p2p-stats-exporter')
 const topic = process.argv[2] // 64-char hex or string
 const mod = new HyperP2PStatsExporter({ topic, enableBackgroundTimers: false })
 await mod.ready()   // joins swarm when topic set
 // ... application logic ...
 await mod.close()
 ```
-`modules/observability/hyper-p2p-stats-exporter/`
+## Docs
-See [`modules/_shared/MODULE_SYSTEM.md`](../../_shared/MODULE_SYSTEM.md).
+- [docs/api.md](docs/api.md) — constructor, methods, events, errors
 - [docs/architecture.md](docs/architecture.md) — wire types, state, composition
 - [../../_shared/PRODUCTION.md](../../_shared/PRODUCTION.md) — production checklist
 - [../../_shared/DOC_STANDARDS.md](../../_shared/DOC_STANDARDS.md) — documentation standards
 ## Test
 ```bash
 npm install && npm test
 ```
@@ -1,23 +1,84 @@
-# hyper-p2p-stats-exporter API
+# API: hyper-p2p-stats-exporter
-**Status:** scaffold · **Protocol:** `stats-exporter/v1`
+**Protocol:** `stats-exporter/v1`
-## Class `HyperP2PStatsExporter`
+**Export:** `HyperP2PStatsExporter`
-Scaffold stub — methods throw `not implemented: scaffold` until promoted to production tier.
+## Overview
-### `constructor(opts?)`
+Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
-### `getStats()`
+## Constructor
-Returns `{ created, errors, protocol, tier: 'scaffold' }`.
+```js
 const mod = new HyperP2PStatsExporter(opts)
 ```
-### `ready()`
+| Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `topic` | `string` | `Buffer` | `null` | Hyperswarm topic; required for P2P `ready()` |
 | `keyPair` | KeyPair | random | Ed25519 key pair |
-Resolves immediately (no-op).
+## Methods
-## Wire (planned)
+### `register(name, getStatsFn)`
-| Message | Direction | Notes |
+- **Returns:** `value`
-|---------|-----------|-------|
+- **Throws:**
-| TBD | gossip | Defined in implementation pass |
+  - `Error: getStatsFn required`
  - `Error: name required`
 ### `unregister(name)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `snapshot(—)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `toJSON(—)`
 - **Returns:** `value`
 - **Throws:** — (none documented in method body)
 ### `getStats(—)`
 - **Returns:** `object`
 - **Throws:** — (none documented in method body)
 ### `ready(—)`
 - **Returns:** `Promise`
 - **Throws:** — (none documented in method body)
 ### `close(—)`
 - **Returns:** `Promise<void>`
 - **Throws:** — (none documented in method body)
 ## Events
 | Event | Payload |
 |-------|---------|
 | `snapshot` | out |
 ## getStats()
 Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
 Library-only modules may include `mode: 'local'`.
 ## Errors
 Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 ## P2P
 When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `stats-exporter/v1`.
 ## Testing
 ```bash
 npm install && npm test
 ```
@@ -1,15 +1,27 @@
-# hyper-p2p-stats-exporter architecture
+# Architecture: hyper-p2p-stats-exporter
-**Tier:** scaffold · **Category:** `observability`
+**Category:** General
-## Role
+```mermaid
 flowchart LR
  App[Application] --> Mod[HyperP2PStatsExporter]
  Mod --> Mux[Protomux stats-exporter/v1]
  Mux --> Swarm[Hyperswarm]
 ```
-Stats export format.
+## Wire messages
 | type | fields | direction | behavior |
 |------|--------|-----------|----------|
 | *(local only)* | — | — | No gossip wire types |
 ## State model
 - In-memory `Map` / `Set` structures for hot path
 - Optional Hyperbee/Hypercore persistence when `storageDir` or `memoryOnly` is configured
 - `close()` tears down swarm, timers, and clears ephemeral state
 ## Composition
-Uses `../../_shared/p2p-bare.js` for Hyperswarm + Protomux when implemented. Does **not** duplicate Holepunch core storage/transport.
+Composes with: see MODULE_CATEGORIES.md.
 ## Holepunch boundary
 Inspiration: n/a
@@ -3,6 +3,8 @@ const { HyperP2PStatsExporter } = require('../index.js')
 async function main () {
  const m = new HyperP2PStatsExporter()
-  console.log('[scaffold]', m.getStats())
+  m.register('demo', () => ({ ok: true }))
  console.log('[stats-exporter]', m.snapshot())
  await m.close()
 }
 main().catch(console.error)
@@ -3,6 +3,9 @@ const { HyperP2PTraceSpan } = require('../index.js')
 async function main () {
  const m = new HyperP2PTraceSpan()
-  console.log('[scaffold]', m.getStats())
+  const id = m.startSpan('example')
  m.endSpan(id)
  console.log('[trace-span]', m.getStats())
  await m.close()
 }
 main().catch(console.error)