update

modules/cli/blind-peering-cli.md

@@ -1,44 +1,62 @@
-# blind-peering-cli - Blind Peering CLI
+# blind-peering-cli
 
-## Overview
+CLI for interacting with blind-peer services.
 
-blind-peering-cli provides a command-line interface for interacting with blind peers. It supports seeding Hypercores and Hyperdrives via blind-peer services.
+## Install
 
-## Installation
-
-```bash
-npm install -g blind-peering-cli
+```sh
+npm i -g blind-peering-cli
 ```
 
 ## Usage
 
-```bash
+```sh
 blind-peering --help
 ```
 
+## Examples
+
 ### Seed a Hypercore
 
-```bash
+```sh
 blind-peering seed --core --blind-peer-key <blind-peer-rpc-key> <hypercore-key>
 ```
 
-### Seed via Autodiscovery
+### Seed via autodiscovery
 
-```bash
+```sh
 blind-peering seed --core \
-  --auto-disc-db <autobase-discovery-db-key> \
+  --auto-disc-db <autobase-discovery-key> \
   --service-name <service-name> \
   <hypercore-key>
 ```
 
-## Notes
+### Get identity
 
-- Only trusted peers can request seeding
-- Use `blind-peering identity` to get your DHT public key
+```sh
+blind-peering identity
+```
+
+## Best Practices
+
+- Use trusted peers only; blind-peer admins must whitelist your DHT key.
+
+## Performance
+
+- Seeding performance depends on blind-peer relay availability.
+
+## Security
+
+- Treat DHT keys as sensitive identifiers.
+
+## Error Handling
+
+- CLI exits non-zero on invalid inputs or connection errors.
+
+## Integration
+
+- Works with blind-peer relays and autodiscovery services.
 
 ## License
 
 Apache-2.0
-
----
-**Module Type**: Tooling | **Ecosystem Role**: Blind Peer Client | **Dependencies**: blind-peering

modules/docs/slips.md

@@ -4,20 +4,20 @@ SatoshiLabs Improvement Proposals repository.
 
 ## Overview
 
-Contains SLIP specifications and status tracking, used as reference docs.
+Contains SLIP specifications and status tracking, modeled after the BIP process for non-Bitcoin protocols.
 
 ## Examples
 
 ### Read a proposal
 
 ```text
-Open a SLIP markdown file to review the spec.
+Open a SLIP markdown file (e.g., slip-0010.md) to review the spec.
 ```
 
 ### Track status
 
 ```text
-Use the README table for proposal status.
+Use the README table for proposal status and lifecycle.
 ```
 
 ### Link from docs

modules/lib/libbase64.md

@@ -1,66 +1,68 @@
 # libbase64
 
-C base64 encoder/decoder library.
-
-## Install
-
-Build as a C library; see repo for details.
+Base64 encoder/decoder library in C.
 
 ## Overview
 
-- Provides base64 encoding/decoding in C.
+`libbase64` provides base64 and base64url encoding/decoding helpers for UTF-8 and UTF-16 output buffers.
 
-## Architecture
+## API (C)
 
-```mermaid
-flowchart LR
-  A[Input bytes] --> B[libbase64]
-  B --> C[Base64]
-```
+### Encoding
 
-## API
+- `base64__encode_utf8(buffer, buffer_len, string, string_len, url_safe)`
+- `base64__encode_utf16le(buffer, buffer_len, string, string_len, url_safe)`
 
-See `include/base64.h` for public C API.
+### Decoding
+
+- `base64__decode_utf8(string, string_len, buffer, buffer_len)`
+- `base64__decode_utf16le(string, string_len, buffer, buffer_len)`
 
 ## Examples
 
-### 1) Include header
+### Encode UTF-8
 
 ```c
-#include "base64.h"
+size_t out_len = 0;
+base64__encode_utf8(buf, len, NULL, &out_len, false);
+utf8_t *out = malloc(out_len + 1);
+base64__encode_utf8(buf, len, out, &out_len, false);
 ```
 
-### 2) Encode
+### Decode
 
-```text
-Use functions in base64.h to encode buffers.
+```c
+size_t out_len = 0;
+base64__decode_utf8(str, str_len, NULL, &out_len);
+uint8_t *out = malloc(out_len);
+base64__decode_utf8(str, str_len, out, &out_len);
 ```
 
-### 3) Decode
+### URL-safe encoding
 
-```text
-Use functions in base64.h to decode buffers.
+```c
+base64__encode_utf8(buf, len, out, &out_len, true);
 ```
 
 ## Best Practices
 
-- Validate buffer sizes for outputs.
+- Call with `string == NULL` to compute output length.
 
-## Performance Notes
+## Performance
 
-- Suitable for high-throughput encoding.
+- Linear time encoding/decoding with low overhead.
 
-## Security Considerations
+## Security
 
-- Base64 is not encryption.
-
-## Integration Notes
-
-- Used by native components and bindings.
+- Base64 is not encryption; do not treat it as secure.
 
 ## Error Handling
 
-- Check return codes from C API.
+- Returns `-1` on insufficient buffer space or invalid characters.
+
+## Integration
+
+- Used by native bindings and encoding utilities.
 
 ## License
 

modules/lib/libfs.md

@@ -1,66 +1,65 @@
 # libfs
 
-File system library for C built on libuv.
-
-## Install
-
-Build as a C library; see repository for build instructions.
+File system library built on libuv.
 
 ## Overview
 
-- Provides async filesystem APIs via libuv.
+`libfs` wraps libuv filesystem APIs with a richer request structure, supporting async operations and extra utilities like xattrs and file locking.
 
-## Architecture
+## API (C)
 
-```mermaid
-flowchart LR
-  A[FS call] --> B[libfs]
-  B --> C[libuv]
-```
+### Core request types
 
-## API
+- `fs_open_t`, `fs_read_t`, `fs_write_t`, `fs_stat_t`, `fs_truncate_t`
+- `fs_mkdir_t`, `fs_rmdir_t`, `fs_unlink_t`, `fs_rename_t`
+- `fs_lock_t`, `fs_get_attr_t`, `fs_set_attr_t`, `fs_list_attrs_t`
 
-See `include/fs.h` for the public C API.
+### Callback signatures
+
+- `fs_open_cb`, `fs_read_cb`, `fs_write_cb`, `fs_stat_cb`, etc.
 
 ## Examples
 
-### 1) Include header
+### Open + read
 
 ```c
-#include "fs.h"
+fs_open_t open_req = { .flags = O_RDONLY, .mode = 0, .cb = on_open };
+fs_open(loop, &open_req, "file.txt");
 ```
 
-### 2) Open file
+### Read batch
 
-```text
-Use fs.h helpers for async file IO.
+```c
+fs_read_batch_t r = { .bufs = bufs, .offsets = offs, .batched = n, .cb = on_read };
+fs_read_batch(loop, &r, fd);
 ```
 
-### 3) Read directory
+### Set extended attribute
 
-```text
-Use directory traversal helpers from fs.h.
+```c
+fs_set_attr_t req = { .cb = on_set };
+fs_set_attr(loop, &req, fd, "user.meta", value, value_len);
 ```
 
 ## Best Practices
 
-- Use libuv loops consistently across modules.
+- Reuse libuv loops consistently across modules.
 
-## Performance Notes
+## Performance
 
-- Async operations reduce blocking.
+- Async I/O reduces blocking on slow storage.
 
-## Security Considerations
+## Security
 
-- Validate input paths for untrusted sources.
-
-## Integration Notes
-
-- Used by several native bindings.
+- Validate untrusted paths before operations.
 
 ## Error Handling
 
-- Check callback error codes.
+- Check status codes in callbacks.
+
+## Integration
+
+- Used by native bindings like `tiny-fs-native`.
 
 ## License
 

modules/lib/libhex.md

@@ -2,65 +2,71 @@
 
 Hex encoder/decoder library in C.
 
-## Install
-
-Build as a C library; see repository for build instructions.
-
 ## Overview
 
-- Converts between binary buffers and hex strings.
+`libhex` provides UTF-8 and UTF-16LE encode/decode helpers for hex strings.
 
-## Architecture
+## API (C)
 
-```mermaid
-flowchart LR
-  A[Bytes] --> B[libhex]
-  B --> C[Hex]
-```
+### Encoding
 
-## API
+- `hex__encode_utf8(buffer, buffer_len, string, string_len)`
+- `hex__encode_utf16le(buffer, buffer_len, string, string_len)`
 
-See `include/hex.h` for the public C API.
+### Decoding
+
+- `hex__decode_utf8(string, string_len, buffer, buffer_len)`
+- `hex__decode_utf16le(string, string_len, buffer, buffer_len)`
+
+### Inline wrappers
+
+- `hex_encode_utf8`, `hex_decode_utf8`, `hex_encode_utf16le`, `hex_decode_utf16le`
 
 ## Examples
 
-### 1) Include header
+### Encode
 
 ```c
-#include "hex.h"
+size_t out_len = 0;
+hex__encode_utf8(buf, len, NULL, &out_len);
+utf8_t *out = malloc(out_len + 1);
+hex__encode_utf8(buf, len, out, &out_len);
 ```
 
-### 2) Encode
+### Decode
 
-```text
-Use hex_encode functions to convert to hex strings.
+```c
+size_t out_len = 0;
+hex__decode_utf8(str, str_len, NULL, &out_len);
+uint8_t *out = malloc(out_len);
+hex__decode_utf8(str, str_len, out, &out_len);
 ```
 
-### 3) Decode
+### UTF-16LE output
 
-```text
-Use hex_decode functions to convert to bytes.
+```c
+hex__encode_utf16le(buf, len, out16, &out_len);
 ```
 
 ## Best Practices
 
-- Check buffer sizes before encoding.
+- Validate output buffer size first by passing `NULL`.
 
-## Performance Notes
+## Performance
 
 - Linear time on input length.
 
-## Security Considerations
+## Security
 
 - Hex encoding is not encryption.
 
-## Integration Notes
-
-- Useful in crypto tooling and logging.
-
 ## Error Handling
 
-- Check return values for invalid input.
+- Returns `-1` on invalid characters or insufficient buffer.
+
+## Integration
+
+- Used by tooling and debug utilities.
 
 ## License
 

modules/lib/librpc.md

@@ -1,66 +1,78 @@
 # librpc
 
-Low-level RPC codec implemented in C.
-
-## Install
-
-Build as a C library; see repository for build instructions.
+Low-level RPC codec in C with streaming support.
 
 ## Overview
 
-- Codec for RPC framing and serialization.
+`librpc` defines a compact binary message format for RPC requests, responses, and stream control frames. It uses `compact-encoding` and UTF string views.
 
-## Architecture
+## API (C)
 
-```mermaid
-flowchart LR
-  A[Message] --> B[librpc]
-  B --> C[Encoded RPC]
-```
+### Types
 
-## API
+- `rpc_message_t`
+- `rpc_t`
 
-See `include/rpc.h` for the public C API.
+### Message types
+
+- `rpc_request`
+- `rpc_response`
+- `rpc_stream`
+
+### Stream flags
+
+- `rpc_stream_open`, `rpc_stream_close`, `rpc_stream_pause`, `rpc_stream_resume`
+- `rpc_stream_data`, `rpc_stream_end`, `rpc_stream_destroy`
+- `rpc_stream_error`, `rpc_stream_request`, `rpc_stream_response`
+
+### Functions
+
+- `rpc_preencode_message(state, message)`
+- `rpc_encode_message(state, message)`
+- `rpc_decode_message(state, result)`
 
 ## Examples
 
-### 1) Include header
+### Encode a request
 
 ```c
-#include "rpc.h"
+rpc_message_t msg = { .type = rpc_request, .id = 1, .command = 2, .stream = 0 };
+rpc_preencode_message(&st, &msg);
+rpc_encode_message(&st, &msg);
 ```
 
-### 2) Encode message
+### Decode
 
-```text
-Use rpc.h APIs to encode requests.
+```c
+rpc_message_t msg;
+int rc = rpc_decode_message(&st, &msg);
 ```
 
-### 3) Decode message
+### Stream data
 
-```text
-Use rpc.h APIs to decode responses.
+```c
+rpc_message_t msg = { .type = rpc_stream, .stream = rpc_stream_data };
 ```
 
 ## Best Practices
 
-- Keep message schemas versioned.
+- Validate stream flags before acting on messages.
 
-## Performance Notes
+## Performance
 
-- Efficient binary encoding.
+- Compact encoding minimizes payload size.
 
-## Security Considerations
+## Security
 
-- Validate sizes and bounds when decoding.
-
-## Integration Notes
-
-- Used by bindings and cross-language tools.
+- Validate lengths and bounds when decoding.
 
 ## Error Handling
 
-- Check return codes from encode/decode.
+- `rpc_error` and `rpc_partial` indicate decode issues.
+
+## Integration
+
+- Used by higher-level RPC systems in the stack.
 
 ## License
 

modules/lib/libz32.md

@@ -1,66 +1,68 @@
 # libz32
 
-Encoder/decoder for z-base-32 in C.
-
-## Install
-
-Build as a C library; see repository for build instructions.
+z-base-32 encoder/decoder library in C.
 
 ## Overview
 
-- z-base-32 encoding for human-friendly keys.
+`libz32` implements z-base-32 encoding for human-friendly identifiers. It provides UTF-8 and UTF-16LE encode/decode helpers.
 
-## Architecture
+## API (C)
 
-```mermaid
-flowchart LR
-  A[Bytes] --> B[libz32]
-  B --> C[z-base-32]
-```
+### Encoding
 
-## API
+- `z32__encode_utf8(buffer, buffer_len, string, string_len)`
+- `z32__encode_utf16le(buffer, buffer_len, string, string_len)`
 
-See `include/z32.h` for the public C API.
+### Decoding
+
+- `z32__decode_utf8(string, string_len, buffer, buffer_len)`
+- `z32__decode_utf16le(string, string_len, buffer, buffer_len)`
 
 ## Examples
 
-### 1) Include header
+### Encode
 
 ```c
-#include "z32.h"
+size_t out_len = 0;
+z32__encode_utf8(buf, len, NULL, &out_len);
+utf8_t *out = malloc(out_len + 1);
+z32__encode_utf8(buf, len, out, &out_len);
 ```
 
-### 2) Encode
+### Decode
 
-```text
-Use z32_encode functions to create z-base-32 strings.
+```c
+size_t out_len = 0;
+z32__decode_utf8(str, str_len, NULL, &out_len);
+uint8_t *out = malloc(out_len);
+z32__decode_utf8(str, str_len, out, &out_len);
 ```
 
-### 3) Decode
+### Human-friendly ids
 
 ```text
-Use z32_decode functions to recover bytes.
+Use z-base-32 for keys that users copy manually.
 ```
 
 ## Best Practices
 
-- Use z-base-32 for human-friendly identifiers.
+- Use z-base-32 for display; store raw bytes internally.
 
-## Performance Notes
+## Performance
 
 - Linear time encoding/decoding.
 
-## Security Considerations
+## Security
 
 - Encoding is not encryption.
 
-## Integration Notes
-
-- Used by key encoding utilities.
-
 ## Error Handling
 
-- Check return codes for invalid input.
+- Returns `-1` on invalid input or insufficient buffer.
+
+## Integration
+
+- Used by key encoding utilities and human-readable IDs.
 
 ## License
 

modules/metrics/thread-stats.md

@@ -10,13 +10,13 @@ npm i thread-stats
 
 ## Overview
 
-Returns an array of stats for threads within the current process.
+Returns an array of stats for threads within the current process using native bindings.
 
 ## API
 
 ### `threadStats()`
 
-- **returns** array of stats objects
+- **returns** array of stats objects (fields depend on platform)
 
 ## Examples
 
@@ -54,7 +54,7 @@ const stats = threadStats().filter((s) => s.user > 0)
 
 ## Error Handling
 
-- Handle environments that do not support thread stats.
+- Handle environments that do not support thread stats or return empty arrays.
 
 ## Integration
 

modules/pear/pear-prerelease.md

@@ -5,7 +5,7 @@ CLI for running Pear prerelease workflows.
 ## Install
 
 ```sh
-npm i pear-prerelease
+npm i -g pear-prerelease
 ```
 
 ## CLI

modules/tiny/tiny-timers-native.md

@@ -22,16 +22,16 @@ Provides native implementations of `setTimeout` and `clearTimeout` for non-Node
 ### Delay a function
 
 ```js
-const timers = require('tiny-timers-native')
+const { setTimeout, clearTimeout } = require('tiny-timers-native')
 
-timers.setTimeout(() => console.log('done'), 1000)
+setTimeout(() => console.log('done'), 1000)
 ```
 
 ### Cancel timeout
 
 ```js
-const id = timers.setTimeout(fn, 1000)
-timers.clearTimeout(id)
+const id = setTimeout(fn, 1000)
+clearTimeout(id)
 ```
 
 ### Use as global

modules/tooling/musl-toolchains.md

@@ -8,7 +8,7 @@ Download or use via build tooling.
 
 ## Overview
 
-- Provides musl-based cross toolchains.
+- Provides prebuilt musl cross toolchains for reproducible builds.
 
 ## Architecture
 
@@ -26,7 +26,7 @@ No JS API; toolchain distribution.
 ### 1) Use in CI
 
 ```text
-Configure compiler paths to musl toolchain.
+Configure compiler paths to musl toolchain binaries.
 ```
 
 ### 2) Cross-compile

modules/tooling/ninja-runtime.md

@@ -10,7 +10,7 @@ npm i -g ninja-runtime
 
 ## Overview
 
-- Provides Ninja binaries via npm.
+- Provides Ninja binaries via npm; versions mirror upstream Ninja.
 
 ## Architecture
 

modules/utilities/known-text-files.md

@@ -1,68 +1,65 @@
 # known-text-files
 
-Combined list of text file extensions and common filenames.
+Combined list of text file extensions, dotfiles, and common filenames.
 
 ## Install
 
-```bash
-npm install known-text-files
+```sh
+npm i known-text-files
 ```
 
 ## Overview
 
-- Provides an array of known text file specifiers.
-
-## Architecture
-
-```mermaid
-flowchart LR
-  A[known-text-files] --> B[List]
-```
+Exports an array of known text file specifiers such as `.txt`, `.gitignore`, and `dockerfile`.
 
 ## API
 
-#### `const known = require('known-text-files')`
+```js
+const knownTextFiles = require('known-text-files')
+```
 
 ## Examples
 
-### 1) Check extension
+### Check extensions
 
 ```js
-known.includes('.txt')
+knownTextFiles.includes('.txt') // true
+knownTextFiles.includes('.pdf') // false
 ```
 
-### 2) Build a Set
+### Check dotfiles
 
 ```js
-const set = new Set(known)
+knownTextFiles.includes('.gitignore') // true
 ```
 
-### 3) Use with is-text-filetype
+### Use a Set
 
 ```js
-const isText = require('is-text-filetype')
+const knownSet = new Set(knownTextFiles)
+knownSet.has('dockerfile')
 ```
 
 ## Best Practices
 
-- Use a Set for repeated lookups.
+- Use a `Set` for repeated membership checks.
 
-## Performance Notes
+## Performance
 
-- O(1) lookup with Set.
+- Array lookup is O(n); Set is O(1).
 
-## Security Considerations
+## Security
 
-- Heuristic list only; not a guarantee.
-
-## Integration Notes
-
-- Used by `is-text-filetype`.
+- Heuristic list only; do not rely on for security checks.
 
 ## Error Handling
 
 - No errors expected.
 
+## Integration
+
+- Used by `is-text-filetype`.
+
 ## License
 
 Apache-2.0

modules/utilities/semifies.md

@@ -1,6 +1,6 @@
 # semifies
 
-Lightweight semver range check.
+Minimal semver range checker.
 
 ## Install
 
@@ -10,7 +10,7 @@ npm i semifies
 
 ## Overview
 
-`semifies` provides a minimal `semver.satisfies`-style function for version range checks.
+`semifies` implements a small subset of `semver.satisfies` with support for common range patterns. It passes semver test fixtures but keeps the implementation lean.
 
 ## API
 
@@ -20,45 +20,47 @@ npm i semifies
 
 ## Examples
 
-### Basic range check
+### Basic ranges
 
 ```js
 const semifies = require('semifies')
 
-semifies('1.2.3', '^1.0.0')
+semifies('1.5.0', '^1.3.0') // true
+semifies('2.0.0', '^1.3.0') // false
+```
+
+### OR ranges
+
+```js
+semifies('2.0.0', '^1.3.0 || ~2.0.0') // true
 ```
 
 ### Exact match
 
 ```js
-semifies('1.2.3', '1.2.3')
-```
-
-### Non-match
-
-```js
-semifies('2.0.0', '^1.0.0')
+semifies('1.2.3', '1.2.3') // true
 ```
 
 ## Best Practices
 
-- Use for simple range checks, not complex semver logic.
+- Use for lightweight gating and CLI checks.
+- Use full `semver` if you need edge-case handling.
 
 ## Performance
 
-- Very small and fast.
+- Fast path for common ranges.
 
 ## Security
 
-- No special considerations.
+- No special concerns.
 
 ## Error Handling
 
-- Returns false on invalid ranges.
+- Invalid ranges return `false`.
 
 ## Integration
 
-- Useful in version gating logic.
+- Useful in build and release tooling.
 
 ## License