Updates

network-discovery/hyper-p2p-capability-discovery/docs/api.md

@@ -1,45 +1,91 @@
 # API: hyper-p2p-capability-discovery
 
-**Protocol:** `capability-discovery/v1`
+**Protocol:** `capability-discovery/v1` · **Export:** `HyperP2PCapabilityDiscovery`, `PROTOCOL`
 
-**Export:** `HyperP2PCapabilityDiscovery`
+## Overview
+
+Gossip registry mapping capability names to peers offering them. Supports multi-peer entries per capability with LWW merge on `at` timestamp.
 
 ## Constructor
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `topic` | string \| Buffer | null | Hyperswarm join topic |
-| `keyPair` | KeyPair | random | Ed25519 identity |
+| `topic` | `string` \| `Buffer` | `null` | Swarm topic |
+| `keyPair` | `KeyPair` | random | `peerHex` identity |
 
 ## Methods
 
-### `registerCapability(name, meta = {})`
+### `registerCapability(name, meta?)`
 
-- **Returns:** `{ name, meta, peer, at }`
-- **Throws:** `ValidationError` if `name` is empty
+- **Returns:** `{ name, meta, peer: peerHex, at }`
+- **Throws:** `assertNonEmpty` on `name`
+- **Gossip:** `{ type: 'cap-register', name, meta, peer, at }`
+- **Emits:** `register`
 
 ### `findByCapability(name)`
 
-- **Returns:** `Array<entry>` for that capability (all peers)
+- **Returns:** array of entries for capability
 
 ### `listCapabilities()`
 
-- **Returns:** `string[]` — capability names with at least one peer
+- **Returns:** array of capability name strings
 
-### `getStats()` / `ready()` / `close()`
+### `ready()` / `close()`
 
-Standard lifecycle; see architecture doc.
+Clears `_byName` on close.
 
 ## Events
 
 | Event | Payload |
 |-------|---------|
 | `register` | local entry |
-| `remote-register` | remote entry |
+| `remote-register` | merged remote entry |
 | `closed` | — |
 
+## getStats()
+
+`registered`, `gossipIn`, `gossipOut`, `capabilities` (name count), `peers` (total entries), `protocol`.
+
+## Wire
+
+| type | fields | behavior |
+|------|--------|----------|
+| `cap-register` | `name`, `meta`, `peer`, `at` | LWW per `(name, peer)` bucket |
+
+## Errors
+
+`assertNonEmpty` on `name` in public methods.
+
+See [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
+
+## P2P
+
+`_onGossip` resolves `peer` from message or `peerInfo.publicKey`.
+
 ## Testing
 
 ```bash
-npm install && npm test
+cd modules/network-discovery/hyper-p2p-capability-discovery && npm test
 ```
+
+## Composition
+
+`hyper-p2p-topic-announcer`, `hyper-p2p-seeder-registry`, `hyper-p2p-discovery-health`.
+
+## Example
+
+See [`examples/basic.js`](../examples/basic.js).
+
+## Remote merge rules
+
+- Incoming `cap-register` ignored without `name`
+- Peer id from `data.peer` or gossip sender `publicKey`
+- Replace bucket entry when `at >= prev.at`
+
+## Lifecycle
+
+Call `ready()` before expecting gossip side effects. `close()` destroys swarm and clears capability map.
+
+## See also
+
+[`docs/architecture.md`](architecture.md), [`../../MODULE_CATEGORIES.md`](../../MODULE_CATEGORIES.md).

network-discovery/hyper-p2p-capability-discovery/docs/architecture.md

@@ -1,18 +1,17 @@
 # Architecture: hyper-p2p-capability-discovery
 
-**Category:** network-discovery
+**Protocol:** `capability-discovery/v1` · **Category:** network-discovery
 
 ## Wire messages
 
-| type | fields | direction | behavior |
-|------|--------|-----------|----------|
-| `cap-register` | `name`, `meta`, `peer`, `at` | gossip | Upsert peer under capability name |
+| type | direction | fields | behavior |
+|------|-----------|--------|----------|
+| `cap-register` | gossip | `name`, `meta`, `peer`, `at` | LWW merge into `_byName[name][peer]`; emit `remote-register` |
 
 ## State model
 
-- `_byName`: `Map<name, Map<peerHex, entry>>`
-- One entry per peer per capability (LWW on `at`)
+`_byName`: `Map<name, Map<peerHex, entry>>`.
 
 ## Composition
 
-`initModuleSwarm` + `gossipSend` from `../../_shared/p2p-bare.js`.
+`hyper-p2p-topic-announcer`, `hyper-p2p-seeder-registry`.