Expand category docs and module APIs across the library.

Manual pass adds helpers (listChannels, taskCounts, openProposals), richer getStats with protocol fields, category README hubs, and tightened api.md for core, messaging, network, routing, supercomputer, and consensus modules.

Co-authored-by: Cursor <[email protected]>

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

@@ -1,91 +1,54 @@
 # API: hyper-p2p-capability-discovery
 
-**Protocol:** `capability-discovery/v1` · **Export:** `HyperP2PCapabilityDiscovery`, `PROTOCOL`
+**Protocol:** `capability-discovery/v1` · **Export:** `HyperP2PCapabilityDiscovery`
 
 ## Overview
 
-Gossip registry mapping capability names to peers offering them. Supports multi-peer entries per capability with LWW merge on `at` timestamp.
+`HyperP2PCapabilityDiscovery` — P2P module. See [`README.md`](../README.md) and [`architecture.md`](architecture.md).
 
 ## Constructor
 
+```js
+const mod = new HyperP2PCapabilityDiscovery(opts)
+```
+
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `topic` | `string` \| `Buffer` | `null` | Swarm topic |
-| `keyPair` | `KeyPair` | random | `peerHex` identity |
+| `topic` | Buffer \| string \| null | `null` | Hyperswarm topic; omit for local-only |
+| `keyPair` | KeyPair | random | Discovery identity |
 
 ## Methods
 
-### `registerCapability(name, meta?)`
+### `registerCapability(...)`
 
-- **Returns:** `{ name, meta, peer: peerHex, at }`
-- **Throws:** `assertNonEmpty` on `name`
-- **Gossip:** `{ type: 'cap-register', name, meta, peer, at }`
-- **Emits:** `register`
+Public API on `HyperP2PCapabilityDiscovery`. See [`index.js`](../index.js) for parameters and return types.
 
-### `findByCapability(name)`
+### `findByCapability(...)`
 
-- **Returns:** array of entries for capability
+Public API on `HyperP2PCapabilityDiscovery`. See [`index.js`](../index.js) for parameters and return types.
 
-### `listCapabilities()`
+### `listCapabilities(...)`
 
-- **Returns:** array of capability name strings
+Public API on `HyperP2PCapabilityDiscovery`. See [`index.js`](../index.js) for parameters and return types.
 
-### `ready()` / `close()`
+### `getStats() → object`
 
-Clears `_byName` on close.
+Metrics plus `protocol: 'capability-discovery/v1'`.
 
-## Events
+### `async ready()`
 
-| Event | Payload |
-|-------|---------|
-| `register` | local entry |
-| `remote-register` | merged remote entry |
-| `closed` | — |
+Joins Hyperswarm when `topic` is set; opens Protomux channel.
 
-## getStats()
+### `async close()`
 
-`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).
+Tears down swarm and clears local state; emits `closed` where applicable.
 
 ## P2P
 
-`_onGossip` resolves `peer` from message or `peerInfo.publicKey`.
+Gossip / sync over Protomux `capability-discovery/v1` when `topic` is configured.
 
 ## Testing
 
 ```bash
-cd modules/network-discovery/hyper-p2p-capability-discovery && npm test
+npm install && 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/index.js

@@ -40,6 +40,16 @@ class HyperP2PCapabilityDiscovery extends EventEmitter {
     return peers ? [...peers.values()] : []
   }
 
+  findFirst (name) {
+    const list = this.findByCapability(name)
+    return list.length ? list[0] : null
+  }
+
+  peerCount (name) {
+    const peers = this._byName.get(name)
+    return peers ? peers.size : 0
+  }
+
   listCapabilities () {
     return [...this._byName.keys()]
   }