update

modules/docs/pear-workshop.md

@@ -4,31 +4,49 @@ Workshop materials and exercises for the Pear Runtime.
 
 ## Overview
 
-`pear-workshop` provides guided exercises and setup instructions for learning the Pear Runtime.
+`pear-workshop` is a guided learning repo with installation steps, OS-specific PATH setup, and a sequence of exercises covering Pear CLI, Hypercore, and Hyperswarm workflows.
+
+## Requirements
+
+- Node.js + npm (used to bootstrap Pear)
+
+## Setup (quick)
+
+```sh
+npx pear
+```
+
+Then add the Pear bin directory to your PATH (platform-specific instructions are in the README).
+
+## Outline
+
+- Setup
+- Pear Preamble
+- Exercises: `pear-init`, `pear-run`, `make-chat-app`, `pear-stage`, `pear-seed`, `connecting-peers`
 
 ## Examples
 
-### Install Pear runtime
+### Install and run runtime
 
 ```text
-Follow the workshop steps to install Pear via npx and PATH setup.
+Run `npx pear` then `npx pear run pear://runtime` to complete setup.
 ```
 
-### Complete an exercise
+### Follow an exercise
 
 ```text
-Follow exercises like pear-init, pear-run, pear-stage, and make-chat-app.
+Open exercises/01-pear-init/readme.md and follow the steps.
 ```
 
-### Share results
+### Update PATH
 
 ```text
-Use the workshop exercises to build and share a Pear app.
+Use the OS-specific instructions in README to expose `pear`.
 ```
 
 ## Best Practices
 
-- Keep workshop instructions in sync with the latest Pear CLI.
+- Keep workshop steps aligned with current Pear CLI.
 
 ## Performance
 
@@ -36,7 +54,7 @@ Use the workshop exercises to build and share a Pear app.
 
 ## Security
 
-- Avoid posting secrets in workshop repositories.
+- Do not share private keys from workshop exercises.
 
 ## Error Handling
 

modules/docs/slips.md

@@ -1,34 +1,39 @@
 # slips
 
-SatoshiLabs Improvement Proposals repository.
+SatoshiLabs Improvement Proposals (SLIPs) repository.
 
 ## Overview
 
-Contains SLIP specifications and status tracking, modeled after the BIP process for non-Bitcoin protocols.
+`slips` is a specs repository modeled after BIPs for documenting protocol and ecosystem changes that do not belong in Bitcoin’s BIP process. Each SLIP includes a rationale and technical specification, with status tracking in the README.
+
+## Structure
+
+- `slip-XXXX.md` specs
+- README table of numbers, titles, types, and statuses
 
 ## Examples
 
-### Read a proposal
+### Read a spec
 
 ```text
-Open a SLIP markdown file (e.g., slip-0010.md) to review the spec.
+Open slip-0010.md to review the spec.
 ```
 
-### Track status
+### Check status
 
 ```text
-Use the README table for proposal status and lifecycle.
+Use the README table for status (Draft/Final/Active/etc.).
 ```
 
-### Link from docs
+### Reference in docs
 
 ```text
-Reference SLIPs from your protocol documentation.
+Link to specific SLIP numbers when describing protocol behavior.
 ```
 
 ## Best Practices
 
-- Keep references to specific SLIP numbers for clarity.
+- Cite specific SLIP numbers in technical documentation.
 
 ## Performance
 
@@ -44,7 +49,7 @@ Reference SLIPs from your protocol documentation.
 
 ## Integration
 
-- Useful as a standards reference.
+- Used as standards reference for crypto/protocol work.
 
 ## License
 

modules/hyper/hyper-cmd-lib-keys.md

@@ -1,68 +1,86 @@
 # hyper-cmd-lib-keys
 
-Utility functions for key pairs and allow lists.
+Key helper utilities for hyper-cmd tooling.
 
 ## Install
 
-```bash
+```sh
 npm i hyper-cmd-lib-keys
 ```
 
 ## Overview
 
-- Key management helpers used by hyper-cmd tools.
-
-## Architecture
-
-```mermaid
-flowchart LR
-  A[keys] --> B[KeyPair]
-  A --> C[Allow list]
-```
+Provides helpers to parse keypairs, generate random bytes, and prepare allow lists from hex strings.
 
 ## API
 
-Library module; see source for exported helpers.
+### `parseKeyPair(jsonString)`
+
+- Parses a JSON string with hex `publicKey` and `secretKey`.
+- Returns `{ publicKey: Buffer, secretKey: Buffer }`.
+
+### `randomBytes(n)`
+
+- Returns a Buffer of `n` cryptographically secure random bytes.
+
+### `prepKey(hex)`
+
+- Converts a hex public key string to a Buffer.
+
+### `prepKeyList(keys)`
+
+- Converts an array of hex strings to Buffers.
+
+### `checkAllowList(allow, key)`
+
+- Returns `true` if `key` Buffer exists in `allow` array.
 
 ## Examples
 
-### 1) Import
+### Parse a keypair
 
 ```js
-const keys = require('hyper-cmd-lib-keys')
+const { parseKeyPair } = require('hyper-cmd-lib-keys')
+
+const kp = parseKeyPair(fs.readFileSync('keypair.json', 'utf8'))
 ```
 
-### 2) Use with hyper-cmd
+### Allow list check
 
 ```js
-// integrate key helpers in a CLI
+const { prepKeyList, checkAllowList } = require('hyper-cmd-lib-keys')
+
+const allow = prepKeyList(['abc123...'])
+const ok = checkAllowList(allow, Buffer.from('abc123...', 'hex'))
 ```
 
-### 3) Manage allow lists
+### Random seed
 
 ```js
-// helper functions to read/write allow lists
+const { randomBytes } = require('hyper-cmd-lib-keys')
+
+const seed = randomBytes(32)
 ```
 
 ## Best Practices
 
 - Store key material in protected locations.
 
-## Performance Notes
+## Performance
 
-- Minimal overhead.
+- Minimal overhead; uses sodium for random bytes.
 
-## Security Considerations
+## Security
 
 - Treat key files as secrets.
 
-## Integration Notes
-
-- Used by `hyper-cmd-lib-coord` and `hyperssh`.
-
 ## Error Handling
 
-- Errors surface as exceptions from IO helpers.
+- `parseKeyPair` throws for invalid JSON or missing fields.
+
+## Integration
+
+- Used by hyper-cmd tooling and identity management.
 
 ## License
 

modules/hyper/hyperswarm-doctor.md

@@ -1,51 +1,65 @@
-# @hyperswarm/doctor - Hyperswarm Debug Tool
+# @hyperswarm/doctor
+
+CLI debugging tool for Hyperswarm connectivity.
+
+## Install
+
+```sh
+npm i -g @hyperswarm/doctor
+```
 
 ## Overview
 
-@hyperswarm/doctor is a CLI debugging tool for Hyperswarm. It can print environment diagnostics and run a server/client transfer test.
-
-### Key Features
-
-- **Diagnostics**: Print swarm environment info
-- **Test server**: Spin up test server
-- **Test client**: Connect and test transfer
-
-## Installation
-
-```bash
-npm install -g @hyperswarm/doctor
-```
+`@hyperswarm/doctor` prints environment diagnostics and can run a server/client transfer test to verify connectivity.
 
 ## Usage
 
-```bash
+```sh
 hyperswarm-doctor
 hyperswarm-doctor --server
-hyperswarm-doctor --client=pubkey
+hyperswarm-doctor --client=<server-public-key>
 ```
 
 ## Examples
 
-### Server
+### Print diagnostics
 
-```bash
+```sh
+hyperswarm-doctor
+```
+
+### Run server
+
+```sh
 hyperswarm-doctor --server
 ```
 
-### Client
+### Run client
 
-```bash
+```sh
 hyperswarm-doctor --client=<server-public-key>
 ```
 
 ## Best Practices
 
-- Run server and client on different hosts for full test
-- Use when debugging connectivity issues
+- Run server and client on different hosts to test NAT traversal.
+
+## Performance
+
+- Test transfers are small; primary cost is DHT connectivity.
+
+## Security
+
+- Share server public keys only with intended testers.
+
+## Error Handling
+
+- Non-zero exit indicates a connectivity or transfer failure.
+
+## Integration
+
+- Useful when debugging Hyperswarm-based apps.
 
 ## License
 
 Apache-2.0
-
----
-**Module Type**: Tooling | **Ecosystem Role**: Networking Diagnostics | **Dependencies**: hyperswarm

modules/lib/libjsi.md

@@ -1,66 +1,67 @@
 # libjsi
 
-React Native JavaScript Interface (JSI) on top of libjs.
-
-## Install
-
-Build as a C library; see repository for build instructions.
+React Native JSI implementation backed by libjs.
 
 ## Overview
 
-- Implements JSI using libjs ABI.
+`libjsi` implements the Facebook JSI `Runtime` on top of `libjs`, providing a JSI-compatible engine for native modules.
 
-## Architecture
+## API (C++)
 
-```mermaid
-flowchart LR
-  A[React Native] --> B[libjsi]
-  B --> C[libjs]
-```
+### Classes
 
-## API
+- `JSIPlatform` creates a `js_platform_t` with a `uv_loop_t`
+- `JSIRuntime` implements `jsi::Runtime`
+- `JSIInstrumentation` provides no-op instrumentation
 
-See `include/jsi.h` for the public C API.
+### Runtime methods (examples)
+
+- `evaluateJavaScript(buffer, file)`
+- `prepareJavaScript(buffer, file)`
+- `evaluatePreparedJavaScript(prepared)`
+- `queueMicrotask(fn)` / `drainMicrotasks()`
 
 ## Examples
 
-### 1) Include header
+### Create runtime
 
 ```cpp
-#include "jsi.h"
+JSIPlatform platform;
+JSIRuntime rt(platform);
 ```
 
-### 2) Bind to RN
+### Evaluate JS
 
-```text
-Use JSI runtime with libjs-backed engine.
+```cpp
+auto val = rt.evaluateJavaScript(buffer, "app.js");
 ```
 
-### 3) Build integration
+### Microtasks
 
-```text
-Link libjsi and libjs in your RN native module.
+```cpp
+rt.queueMicrotask(fn);
+rt.drainMicrotasks();
 ```
 
 ## Best Practices
 
-- Match React Native JSI version expectations.
+- Ensure the libjs platform and env lifetimes outlive the runtime.
 
-## Performance Notes
+## Performance
 
-- Performance depends on underlying libjs engine.
+- Performance depends on `libjs` engine and UV loop activity.
 
-## Security Considerations
+## Security
 
-- Follow RN security practices for native modules.
-
-## Integration Notes
-
-- Bridges RN to libjs ABI.
+- Follow React Native native module security practices.
 
 ## Error Handling
 
-- Check JSI API return values.
+- Exceptions are thrown on `libjs` errors.
+
+## Integration
+
+- Bridges React Native JSI to libjs ABI.
 
 ## License
 

modules/lib/libtt.md

@@ -1,66 +1,77 @@
 # libtt
 
-Virtual console extensions built on libuv.
-
-## Install
-
-Build as a C library; see repository for build instructions.
+PTY and terminal helpers built on libuv.
 
 ## Overview
 
-- Console and terminal utilities for native apps.
+`libtt` provides pseudo-terminal (PTY) spawning, IO, resizing, and process control.
 
-## Architecture
+## API (C)
 
-```mermaid
-flowchart LR
-  A[Console] --> B[libtt]
-  B --> C[libuv]
-```
+### Types
 
-## API
+- `tt_pty_t`, `tt_pty_write_t`
+- `tt_term_options_t` (`width`, `height`)
+- `tt_process_options_t` (`file`, `args`, `env`, `cwd`)
 
-See `include/tt.h` for the public C API.
+### Callbacks
+
+- `tt_pty_alloc_cb`, `tt_pty_read_cb`, `tt_pty_write_cb`
+- `tt_pty_exit_cb`, `tt_pty_close_cb`
+
+### Functions
+
+- `tt_pty_spawn(loop, handle, term, process, exit_cb)`
+- `tt_pty_read_start(handle, alloc_cb, read_cb)` / `tt_pty_read_stop(handle)`
+- `tt_pty_write(req, handle, bufs, bufs_len, cb)`
+- `tt_pty_resize(handle, width, height)`
+- `tt_pty_close(handle, cb)`
+- `tt_pty_kill(handle, signum)`
+- `tt_pty_get_pid(handle)`
+- `tt_pty_get_size(handle, &width, &height)`
 
 ## Examples
 
-### 1) Include header
+### Spawn a PTY
 
 ```c
-#include "tt.h"
+tt_term_options_t term = { .width = 80, .height = 24 };
+tt_process_options_t proc = { .file = "/bin/sh" };
+tt_pty_spawn(loop, &pty, &term, &proc, on_exit);
 ```
 
-### 2) Configure terminal
+### Read/write
 
-```text
-Use tt.h helpers for terminal settings.
+```c
+tt_pty_read_start(&pty, alloc_cb, read_cb);
+tt_pty_write(&req, &pty, bufs, nbufs, on_write);
 ```
 
-### 3) Handle IO
+### Resize
 
-```text
-Integrate with libuv event loops.
+```c
+tt_pty_resize(&pty, 100, 40);
 ```
 
 ## Best Practices
 
-- Restore terminal settings on exit.
+- Always restore terminal state on exit.
 
-## Performance Notes
+## Performance
 
-- Minimal overhead for terminal operations.
+- Minimal overhead; IO is event-loop driven.
 
-## Security Considerations
+## Security
 
-- Avoid writing sensitive data to shared terminals.
-
-## Integration Notes
-
-- Useful for CLI tooling.
+- Avoid spawning untrusted commands.
 
 ## Error Handling
 
-- Check return codes for IO errors.
+- Check return codes for spawn and IO errors.
+
+## Integration
+
+- Used by terminal UIs and `tt-native` bindings.
 
 ## License
 

modules/native/simdle-native.md

@@ -10,13 +10,28 @@ npm i simdle-native
 
 ## Overview
 
-Provides fast SIMD helpers for bitwise operations on buffers.
+`simdle-native` provides SIMD-accelerated bitwise operations on buffers. Input buffers must be multiples of 16 bytes and operations are dispatched based on element size (u8/u16/u32).
 
 ## API
 
-### Functions
+### Predicates
 
-- `allo`, `allz`, `and`, `clear`, `clo`, `clz`, `cnt`, `cto`, `ctz`, `not`, `or`, `sum`, `xor`
+- `allo(buf)` / `allz(buf)`
+
+### Unary ops
+
+- `clo(buf, result?)`, `clz(buf, result?)`, `cnt(buf, result?)`
+- `cto(buf, result?)`, `ctz(buf, result?)`
+- `not(buf, result?)`
+
+### Binary ops
+
+- `and(a, b, result?)`, `or(a, b, result?)`, `xor(a, b, result?)`
+- `clear(a, b, result?)`
+
+### Reductions
+
+- `sum(buf)`
 
 ## Examples
 
@@ -24,8 +39,7 @@ Provides fast SIMD helpers for bitwise operations on buffers.
 
 ```js
 const simdle = require('simdle-native')
-
-const count = simdle.cnt(Buffer.from([0xff, 0x00]))
+const count = simdle.cnt(Buffer.from([0xff, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]))
 ```
 
 ### AND two buffers
@@ -34,31 +48,33 @@ const count = simdle.cnt(Buffer.from([0xff, 0x00]))
 const out = simdle.and(a, b)
 ```
 
-### Clear bits
+### Provide result buffer
 
 ```js
-simdle.clear(buf, 0, 8)
+const out = Buffer.alloc(a.length)
+simdle.xor(a, b, out)
 ```
 
 ## Best Practices
 
-- Ensure buffer sizes match for binary ops.
+- Ensure buffer length is a multiple of 16.
+- Pass preallocated `result` buffers to avoid allocations.
 
 ## Performance
 
-- SIMD acceleration makes bit ops fast on supported CPUs.
+- Uses SIMD paths for u8/u16/u32 buffers when available.
 
 ## Security
 
-- Validate inputs to avoid out-of-range access.
+- Validate input sizes to avoid out-of-range access.
 
 ## Error Handling
 
-- Functions may throw on invalid buffer sizes.
+- Throws if buffer lengths are not aligned or mismatch.
 
 ## Integration
 
-- Used in low-level indexing and bitmap logic.
+- Built on `libsimdle` and used in bitset-heavy code.
 
 ## License
 

modules/tiny/tiny-buffer-map.md

@@ -1,6 +1,6 @@
 # tiny-buffer-map
 
-Map-like structure for Buffer keys.
+Minimal Map implementation optimized for Buffer keys.
 
 ## Install
 
@@ -10,47 +10,58 @@ npm i tiny-buffer-map
 
 ## Overview
 
-Provides a small `BufferMap` with Map-like APIs for Buffer keys.
+`tiny-buffer-map` provides a Map-like API where keys are Buffers. Iteration returns Buffer keys.
 
 ## API
 
 ### `new BufferMap()`
 
+Supports the standard Map methods:
+
 - `set(key, value)`
 - `get(key)`
+- `has(key)`
 - `delete(key)`
-- `keys()` / `values()`
+- `clear()`
+- `keys()`, `values()`, `entries()`
+- `[Symbol.iterator]` (iterates entries)
 
 ## Examples
 
-### Use Buffer keys
+### Basic usage
 
 ```js
 const BufferMap = require('tiny-buffer-map')
+const b4a = require('b4a')
 
-const map = new BufferMap()
-map.set(Buffer.from('a'), 1)
-```
-
-### Retrieve values
-
-```js
-const val = map.get(Buffer.from('a'))
+const m = new BufferMap()
+m.set(b4a.from('a'), 'b')
+m.set(b4a.from('c'), 'd')
+m.get(b4a.from('a')) // 'b'
+m.delete(b4a.from('c'))
 ```
 
 ### Iterate
 
 ```js
-for (const key of map.keys()) console.log(key)
+for (const [key, value] of m) {
+  // key is a Buffer
+}
+```
+
+### Has check
+
+```js
+if (m.has(b4a.from('a'))) console.log('present')
 ```
 
 ## Best Practices
 
-- Reuse Buffer instances where possible.
+- Reuse Buffer instances when possible to avoid extra allocations.
 
 ## Performance
 
-- Optimized for small maps.
+- Optimized for small maps and Buffer keys.
 
 ## Security
 
@@ -58,11 +69,11 @@ for (const key of map.keys()) console.log(key)
 
 ## Error Handling
 
-- Handle missing keys gracefully.
+- Missing keys return `undefined` like Map.
 
 ## Integration
 
-- Useful for binary key caches.
+- Useful for binary key caches and protocol maps.
 
 ## License
 

modules/tiny/tiny-timers-native.md

@@ -37,7 +37,9 @@ clearTimeout(id)
 ### Use as global
 
 ```js
+const timers = require('tiny-timers-native')
 global.setTimeout = timers.setTimeout
+global.clearTimeout = timers.clearTimeout
 ```
 
 ## Best Practices

modules/tooling/prettier-config-holepunch.md

@@ -10,29 +10,23 @@ npm i -D prettier-config-holepunch
 
 ## Overview
 
-Provides a shareable Prettier configuration that can be referenced in `.prettierrc`.
+This package provides a shareable Prettier config used across Holepunch repositories.
 
 ## Usage
 
-```json
-"prettier-config-holepunch"
-```
-
-## Examples
-
-### .prettierrc
+### `.prettierrc`
 
 ```json
 "prettier-config-holepunch"
 ```
 
-### package.json
+### `package.json`
 
 ```json
 { "prettier": "prettier-config-holepunch" }
 ```
 
-### Extend in JS config
+### JS config
 
 ```js
 module.exports = { ...require('prettier-config-holepunch') }
@@ -40,7 +34,7 @@ module.exports = { ...require('prettier-config-holepunch') }
 
 ## Best Practices
 
-- Use a single shared config across repos for consistency.
+- Use one shared config across repos for consistent formatting.
 
 ## Performance
 

modules/utilities/get-mime-type.md

@@ -1,45 +1,40 @@
 # get-mime-type
 
-Get a mime-type from a filename or extension.
+Get a MIME type from a filename or extension with no fuzz.
 
 ## Install
 
-```bash
-npm install get-mime-type
+```sh
+npm i get-mime-type
 ```
 
 ## Overview
 
-- Returns MIME types with optional charset.
-
-## Architecture
-
-```mermaid
-flowchart LR
-  A[Name/Ext] --> B[get-mime-type]
-  B --> C[MIME]
-```
+Returns a MIME type for a given filename or extension. If `charset` is `true` (default), appends a charset for known textual types.
 
 ## API
 
-#### `mime = getMimeType(name, charset = true)`
+### `getMimeType(name, charset = true)`
+
+- **name** filename or extension (with or without dot)
+- **returns** `string | null`
 
 ## Examples
 
-### 1) Basic usage
+### Basic usage
 
 ```js
 const getMimeType = require('get-mime-type')
 getMimeType('photo.png')
 ```
 
-### 2) Disable charset
+### Disable charset
 
 ```js
 getMimeType('index.html', false)
 ```
 
-### 3) From extension
+### Extension only
 
 ```js
 getMimeType('.json')
@@ -47,24 +42,24 @@ getMimeType('.json')
 
 ## Best Practices
 
-- Use in combination with magic detection for safety.
+- Combine with magic-byte detection for untrusted files.
 
-## Performance Notes
+## Performance
 
-- O(1) lookup.
+- O(1) lookup from an internal map.
 
-## Security Considerations
+## Security
 
-- Do not rely solely on extension for untrusted files.
-
-## Integration Notes
-
-- Works with `get-file-format`.
+- Do not rely solely on extensions for security decisions.
 
 ## Error Handling
 
 - Returns `null` for unknown extensions.
 
+## Integration
+
+- Works with `get-file-format` and content servers.
+
 ## License
 
 Apache-2.0

modules/utilities/task-backoff.md

@@ -1,6 +1,6 @@
 # task-backoff
 
-Adaptive delay helper for busy loops.
+Adaptive delay helper for tight loops.
 
 ## Install
 
@@ -10,51 +10,56 @@ npm i task-backoff
 
 ## Overview
 
-Helps maintain a target event loop delay by introducing adaptive waits in loops.
+`task-backoff` uses `event-loop-delay` to measure lag and introduces delays to keep event loop latency under a target threshold.
 
 ## API
 
-### `new TaskBackoff({ maxDelay })`
+### `new TaskBackoff({ maxDelay = 100, ref = true })`
+
+- `maxDelay` threshold for backoff (ms)
+- `ref` whether to keep the timer ref’d
 
 ### Methods
 
-- `backoff()`
-- `wait()`
-- `delay()`
+- `backoff()` returns `true` if lag exceeds target
+- `wait()` waits until lag is back under target
+- `delay()` returns current delay delta
+- `destroy()` stops timers and resolves waiters
 
 ## Examples
 
-### Use in a loop
+### Adaptive loop
 
 ```js
 const TaskBackoff = require('task-backoff')
 
-const backoff = new TaskBackoff({ maxDelay: 100 })
+const t = new TaskBackoff({ maxDelay: 100 })
+let i = 0
 while (true) {
-  await doWork()
-  await backoff.wait()
+  if (t.backoff()) await t.wait()
+  console.log('gogo', i++, t.delay())
 }
 ```
 
-### Read current delay
+### Stop
 
 ```js
-const d = backoff.delay()
+t.destroy()
 ```
 
-### Backoff manually
+### Unref timer
 
 ```js
-backoff.backoff()
+const t = new TaskBackoff({ ref: false })
 ```
 
 ## Best Practices
 
-- Use when polling or processing batches.
+- Use in polling loops or batch processors.
 
 ## Performance
 
-- Reduces CPU usage in tight loops.
+- Reduces CPU usage under load.
 
 ## Security
 
@@ -62,11 +67,11 @@ backoff.backoff()
 
 ## Error Handling
 
-- Ensure loop has cancellation or exit conditions.
+- Ensure loops have cancellation paths.
 
 ## Integration
 
-- Useful in network polling or queue workers.
+- Useful for network polling and queue workers.
 
 ## License