update

modules/bare-abort-controller.md

@@ -0,0 +1,138 @@
+# bare-abort-controller - AbortController for Bare
+
+## Overview
+
+bare-abort-controller provides WHATWG `AbortController` and `AbortSignal` implementations for the Bare runtime. It supports abort reasons, `throwIfAborted`, and `AbortController.timeout()`.
+
+### Key Features
+
+- **WHATWG compatible**: Follows DOM spec semantics.
+- **Abort reasons**: Custom error reasons are supported.
+- **Timeout helper**: `AbortController.timeout(ms)` convenience.
+- **EventTarget-based**: `AbortSignal` dispatches `abort` events.
+
+### Use Cases
+
+- **Cancelable operations**: Network or IO cancellation.
+- **Timeouts**: Abort long-running tasks.
+- **Composability**: Share signals across APIs.
+
+## Installation
+
+```bash
+npm install bare-abort-controller
+```
+
+## Quick Start
+
+```js
+const AbortController = require('bare-abort-controller')
+
+const controller = new AbortController()
+controller.signal.addEventListener('abort', () => console.log('aborted'))
+controller.abort()
+```
+
+## API Reference
+
+### `const AbortController = require('bare-abort-controller')`
+
+Exports the `AbortController` class plus `AbortSignal`.
+
+### `new AbortController()`
+
+Creates a controller with a new `signal`.
+
+### `controller.signal`
+
+Returns the associated `AbortSignal`.
+
+### `controller.abort([reason])`
+
+Abort the signal; `reason` defaults to an `AbortError`.
+
+### `AbortController.abort(reason)`
+
+Returns a pre-aborted signal with the provided reason.
+
+### `AbortController.timeout(ms)`
+
+Returns a signal that aborts after `ms` with a `TimeoutError`.
+
+### `AbortSignal`
+
+- `signal.aborted` (boolean)
+- `signal.reason` (any)
+- `signal.throwIfAborted()`
+- `signal.addEventListener('abort', ...)`
+
+## Complete Examples
+
+### Example 1: Abort with Reason
+
+```js
+const AbortController = require('bare-abort-controller')
+
+const c = new AbortController()
+c.signal.addEventListener('abort', (evt) => console.log(evt.type))
+c.abort(new Error('Operation aborted'))
+```
+
+### Example 2: Timeout Signal
+
+```js
+const AbortController = require('bare-abort-controller')
+
+const signal = AbortController.timeout(100)
+signal.addEventListener('abort', () => console.log('timed out'))
+```
+
+### Example 3: throwIfAborted
+
+```js
+const AbortController = require('bare-abort-controller')
+
+const c = new AbortController()
+c.abort()
+c.signal.throwIfAborted()
+```
+
+### Example 4: Pre-aborted Signal
+
+```js
+const AbortController = require('bare-abort-controller')
+
+const signal = AbortController.abort(new Error('nope'))
+console.log(signal.aborted)
+```
+
+## Best Practices
+
+- **Propagate signals** through API layers.
+- **Use timeout signals** to enforce operation limits.
+- **Check `aborted` early** to fail fast.
+
+## Performance Notes
+
+- Event dispatch is lightweight; timers incur normal timeout overhead.
+
+## Security Considerations
+
+- Do not leak sensitive errors in abort reasons to untrusted callers.
+
+## Integration with Other Modules
+
+### With bare-events/web
+
+`AbortSignal` extends `EventTarget` from `bare-events/web`.
+
+## Error Handling
+
+- `throwIfAborted` throws the abort reason when aborted.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Runtime Utility | **Ecosystem Role**: Cancellation | **Dependencies**: bare-events/web

modules/bare-abort.md

@@ -0,0 +1,96 @@
+# bare-abort - Force Process Abort
+
+## Overview
+
+bare-abort triggers an abnormal program termination and generates a crash report. It is a minimal wrapper over a native binding that immediately aborts the process.
+
+### Key Features
+
+- **Immediate abort**: Terminates the process without cleanup.
+- **Crash report**: Produces a diagnostic crash report.
+- **Tiny API**: Single `abort()` function.
+
+### Use Cases
+
+- **Fatal error paths**: Hard-stop on irrecoverable state.
+- **Crash testing**: Verify crash handlers or report pipelines.
+- **Debugging**: Force a dump to inspect system state.
+
+## Installation
+
+```bash
+npm install bare-abort
+```
+
+## Quick Start
+
+```js
+const abort = require('bare-abort')
+
+abort()
+```
+
+## API Reference
+
+### `const abort = require('bare-abort')`
+
+Exports a single function.
+
+### `abort()`
+
+Immediately aborts the process.
+
+**Returns:**
+- Never returns.
+
+## Complete Examples
+
+### Example 1: Guard a Critical Invariant
+
+```js
+const abort = require('bare-abort')
+
+if (!state.isValid) abort()
+```
+
+### Example 2: Crash Test Hook
+
+```js
+const abort = require('bare-abort')
+
+setTimeout(() => abort(), 1000)
+```
+
+### Example 3: Conditional Abort
+
+```js
+const abort = require('bare-abort')
+
+function failIf(cond) {
+  if (cond) abort()
+}
+```
+
+## Best Practices
+
+- **Use sparingly**; abort skips cleanup and can corrupt state.
+- **Log context first** if possible to aid crash diagnostics.
+
+## Performance Notes
+
+- Constant-time; terminates immediately.
+
+## Security Considerations
+
+- Treat as a privileged operation; do not expose to untrusted inputs.
+
+## Error Handling
+
+- None; process terminates immediately.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Runtime Utility | **Ecosystem Role**: Crash Control | **Dependencies**: native binding

modules/bare-addon-jstl.md

@@ -0,0 +1,134 @@
+# bare-addon-jstl
+
+Template repository for creating Bare native addons using `libjstl`. It ships a minimal JS entrypoint that loads the native binding and exposes a tiny API surface so you can replace it with your own addon exports.
+
+## Install
+
+```bash
+npm i bare-addon-jstl
+```
+
+## Overview
+
+- Purpose: starter template for Bare addons powered by `libjstl`.
+- Output: a shared library in `prebuilds/` resolved by Bare's addon loader.
+- Build: uses `bare-make` to generate, build, and install prebuilds.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  A[Your JS API] --> B[index.js]
+  B --> C[binding.js/native loader]
+  C --> D[binding.cc]
+  D --> E[libjstl]
+  E --> F[Native library]
+  B --> G[prebuilds/<host>/...]
+```
+
+## API
+
+#### `const addon = require('bare-addon-jstl')`
+
+The template exports a single function from the native binding:
+
+#### `addon.hello()`
+
+Calls the example native function from `binding.cc` via `binding.js`. Replace this with your own API surface.
+
+## Build & Publish
+
+#### Generate build system
+
+```bash
+bare-make generate [--debug]
+```
+
+#### Build and install prebuilds
+
+```bash
+bare-make build
+bare-make install [--link]
+```
+
+#### Publish prebuilds via GitHub Actions
+
+```bash
+npm version <increment>
+git push && git push --tags
+gh workflow run prebuild --ref <version>
+gh run download --name prebuilds --dir prebuilds
+```
+
+## Examples
+
+### 1) Basic usage
+
+```js
+const addon = require('bare-addon-jstl')
+
+console.log(addon.hello())
+```
+
+### 2) Replace the export surface
+
+```js
+// index.js
+const binding = require('./binding')
+
+exports.hash = binding.hash
+exports.verify = binding.verify
+```
+
+### 3) Add a dependency via cmake-fetch
+
+```cmake
+project(my_addon)
+
+fetch_package("github:holepunchto/liburl")
+
+target_link_libraries(
+  ${bare_addon}
+  PUBLIC
+    url
+)
+```
+
+### 4) Prebuild install with link for fast iteration
+
+```bash
+bare-make install --link
+```
+
+## Best Practices
+
+- Keep the JS surface minimal and forward to native for correctness and speed.
+- Remove any symlinked prebuilds before publishing to npm.
+- Pin `bare-make` and toolchain versions in CI to avoid ABI drift.
+- Use `cmake-fetch` for native deps; avoid vendoring large libraries.
+
+## Performance Notes
+
+- Native execution is fast; overhead is dominated by JS/native crossings.
+- Prefer batching data and avoiding per-item JS/native calls.
+
+## Security Considerations
+
+- Treat prebuilds as privileged binaries; build in trusted CI.
+- Validate untrusted input in native code to avoid memory safety issues.
+- Keep dependency versions in sync across platforms to avoid subtle ABI bugs.
+
+## Integration Notes
+
+- Works with `bare-addon-resolve` and Bare's addon loader.
+- Often paired with `bare-prebuild` and `bare-make` for CI workflows.
+- Use `cmake-fetch` for third-party libraries and `cmake-bare` for toolchain setup.
+
+## Error Handling
+
+- Build errors typically surface from `bare-make` or compiler toolchain output.
+- Runtime errors are emitted by the native binding; expose them as JS exceptions.
+
+## License
+
+Apache-2.0

modules/bare-addon-resolve.md

@@ -0,0 +1,189 @@
+# bare-addon-resolve
+
+Low-level addon resolution algorithm for Bare. Exposes a sync/async iterable wrapper plus generator helpers for driving the resolution process manually.
+
+## Install
+
+```bash
+npm i bare-addon-resolve
+```
+
+## Overview
+
+- Resolves addon specifiers to candidate URLs (file, prebuilds, linked artefacts).
+- Uses a generator protocol so the caller controls I/O (reading package.json, probing files).
+- Supports builtins, linked addons, pre-resolved imports, and host-specific prebuilds.
+
+## Architecture
+
+```mermaid
+flowchart TD
+  A[resolve(specifier, parentURL)] --> B[addon() generator]
+  B --> C{yield package.json?}
+  C -->|caller reads| D[package info]
+  B --> E{yield resolution URL}
+  E -->|caller tests| F[resolved?]
+  F -->|yes| G[RESOLVED]
+  F -->|no| H[continue candidates]
+```
+
+## API
+
+#### `const resolver = resolve(specifier, parentURL[, options][, readPackage])`
+
+Returns an object that is both sync and async iterable. `readPackage(url)` must return parsed JSON or `null`. If it returns a promise, only async iteration is supported.
+
+Options:
+
+```js
+{
+  builtins: [],           // builtin addon specifiers
+  builtinProtocol: 'builtin:',
+  linked: true,
+  linkedProtocol: 'linked:',
+  conditions: [],         // import conditions ("default" always supported)
+  matchedConditions: [],  // array reference, populated during iteration
+  hosts: [],              // e.g. [Bare.Addon.host]
+  extensions: [],         // file extensions for dynamic addons
+  resolutions             // pre-resolved "imports" maps
+}
+```
+
+#### `for (const resolution of resolver)` / `for await (const resolution of resolver)`
+
+Iterate candidate URLs. The first existing candidate is the resolved addon.
+
+#### `resolve.constants`
+
+```js
+{
+  UNRESOLVED,
+  YIELDED,
+  RESOLVED
+}
+```
+
+#### Generator helpers (advanced)
+
+Each yields either `{ package: URL }` or `{ resolution: URL }`:
+
+- `resolve.addon(specifier, parentURL[, options])`
+- `resolve.url(url, parentURL[, options])`
+- `resolve.package(packageSpecifier, packageVersion, parentURL[, options])`
+- `resolve.packageSelf(packageName, packageSubpath, packageVersion, parentURL[, options])`
+- `resolve.preresolved(directoryURL, resolutions[, options])`
+- `resolve.file(filename, parentURL[, options])`
+- `resolve.directory(dirname, version, parentURL[, options])`
+- `resolve.linked(name, version[, options])`
+
+#### Errors
+
+- `INVALID_ADDON_SPECIFIER`
+- `INVALID_PACKAGE_NAME`
+
+## Examples
+
+### 1) Synchronous iteration
+
+```js
+const resolve = require('bare-addon-resolve')
+
+function readPackage(url) {
+  // return parsed package.json or null
+}
+
+for (const url of resolve('./addon', new URL('file:///app/'), readPackage)) {
+  if (exists(url)) {
+    break
+  }
+}
+```
+
+### 2) Async iteration with async package reads
+
+```js
+const resolve = require('bare-addon-resolve')
+
+async function readPackage(url) {
+  return await readJSONIfExists(url)
+}
+
+for await (const url of resolve('my-addon', new URL('file:///app/'), readPackage)) {
+  if (await exists(url)) break
+}
+```
+
+### 3) Custom generator loop
+
+```js
+const resolve = require('bare-addon-resolve')
+
+const gen = resolve.addon('[email protected]', new URL('file:///app/'))
+let next = gen.next()
+
+while (!next.done) {
+  if (next.value.package) {
+    next = gen.next(await readJSONIfExists(next.value.package))
+  } else {
+    const ok = await exists(next.value.resolution)
+    next = gen.next(ok)
+  }
+}
+```
+
+### 4) Host-specific prebuilds
+
+```js
+const resolve = require('bare-addon-resolve')
+
+const opts = { hosts: ['darwin-arm64'], extensions: ['.node'] }
+for (const url of resolve('my-addon', new URL('file:///app/'), opts, () => null)) {
+  console.log(url.href)
+}
+```
+
+### 5) Builtins and linked artefacts
+
+```js
+const resolve = require('bare-addon-resolve')
+
+const opts = {
+  builtins: ['crypto', 'uv'],
+  linkedProtocol: 'linked:'
+}
+
+for (const url of resolve('crypto', new URL('file:///app/'), opts, () => null)) {
+  console.log(url.href)
+}
+```
+
+## Best Practices
+
+- Always pass a `matchedConditions` array when you need to understand why a candidate matched.
+- Use async iteration if package.json reads are async or remote.
+- Provide `hosts` from `Bare.Addon.host` so prebuild selection is correct.
+- Avoid direct generator helpers unless you pin a tilde version range (APIs can change).
+
+## Performance Notes
+
+- Resolution is CPU-light; I/O dominates when probing filesystem candidates.
+- Pre-resolved imports (`resolutions`) can short-circuit directory walking.
+
+## Security Considerations
+
+- Validate untrusted specifiers before calling to avoid path confusion.
+- If you allow linked addons, constrain `linkedProtocol` and validate resolved paths.
+
+## Integration Notes
+
+- Typically used by Bare runtime and loaders.
+- Pairs with `bare-module-resolve` and `bare-semver` for package parsing.
+
+## Error Handling
+
+- Catch `INVALID_ADDON_SPECIFIER` and `INVALID_PACKAGE_NAME` and present user-friendly messages.
+- Treat `UNRESOLVED` as a normal outcome and move to fallback loading.
+
+## License
+
+Apache-2.0

modules/bare-addon-rust.md

@@ -0,0 +1,132 @@
+# bare-addon-rust
+
+Template repository for creating Bare native addons backed by Rust via `bare-rust`. Provides a minimal JS entrypoint that loads the native binding and exposes a placeholder API.
+
+## Install
+
+```bash
+npm i bare-addon-rust
+```
+
+## Overview
+
+- Purpose: starter template for Rust-based Bare addons.
+- Build: `bare-make` drives CMake and Cargo integration.
+- Output: prebuilt shared libraries in `prebuilds/` for Bare addon resolution.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  A[Your JS API] --> B[index.js]
+  B --> C[binding.js/native loader]
+  C --> D[binding.c]
+  D --> E[binding.rs (Rust)]
+  E --> F[Native library]
+```
+
+## API
+
+#### `const addon = require('bare-addon-rust')`
+
+#### `addon.hello()`
+
+Example native function exported from the Rust binding. Replace with your own exports.
+
+## Build & Publish
+
+#### Generate build system
+
+```bash
+bare-make generate [--debug]
+```
+
+#### Build and install prebuilds
+
+```bash
+bare-make build
+bare-make install [--link]
+```
+
+#### Publish workflow
+
+```bash
+npm version <increment>
+git push && git push --tags
+gh workflow run prebuild --ref <version>
+gh run download --name prebuilds --dir prebuilds
+```
+
+## Examples
+
+### 1) Basic usage
+
+```js
+const addon = require('bare-addon-rust')
+
+console.log(addon.hello())
+```
+
+### 2) Add a new Rust export
+
+```rust
+// binding.rs
+#[no_mangle]
+pub extern "C" fn add(a: i32, b: i32) -> i32 {
+  a + b
+}
+```
+
+```js
+// index.js
+const binding = require('./binding')
+
+exports.add = binding.add
+```
+
+### 3) Link a native dependency
+
+```cmake
+project(my_addon)
+
+fetch_package("github:holepunchto/liburl")
+
+target_link_libraries(${bare_addon} PUBLIC url)
+```
+
+### 4) Faster dev iteration
+
+```bash
+bare-make install --link
+```
+
+## Best Practices
+
+- Keep the JS surface small; marshal data once per call.
+- Use `cmake-cargo` for clean Rust/CMake wiring.
+- Ensure `Cargo.lock` is committed for reproducible builds.
+- Remove symlinked prebuilds before publishing.
+
+## Performance Notes
+
+- Rust code executes natively; avoid chatty JS/native interfaces.
+- Use zero-copy buffers where possible for large data.
+
+## Security Considerations
+
+- Treat native code as part of the trusted compute base.
+- Validate inputs at the boundary to avoid UB or panics.
+
+## Integration Notes
+
+- Pairs with `bare-make`, `cmake-bare`, and `cmake-cargo`.
+- Prebuilds are discovered by `bare-addon-resolve` and Bare runtime.
+
+## Error Handling
+
+- Native panics or exceptions will surface as JS errors.
+- Prefer returning explicit error codes or exceptions from Rust.
+
+## License
+
+Apache-2.0

modules/bare-ansi-escapes.md

@@ -0,0 +1,116 @@
+# bare-ansi-escapes - ANSI Escape Utilities
+
+## Overview
+
+bare-ansi-escapes provides helpers to generate ANSI escape sequences and a key decoder stream for parsing terminal key input. It includes constants for cursor movement, screen erasing, and SGR styling codes.
+
+### Key Features
+
+- **ANSI generators**: Cursor control, erase, scroll, and styling codes.
+- **Constants**: `ESC`, `CSI`, and `SGR` helpers.
+- **Key decoder**: Stream parser via `bare-ansi-escapes/key-decoder`.
+
+### Use Cases
+
+- **Terminal UIs**: Draw and update terminal output.
+- **Key handling**: Decode input sequences to key events.
+- **CLI styling**: Apply colors and formatting.
+
+## Installation
+
+```bash
+npm install bare-ansi-escapes
+```
+
+## Quick Start
+
+```js
+const ansi = require('bare-ansi-escapes')
+
+process.stdout.write(ansi.cursorHide)
+```
+
+## API Reference
+
+### Constants
+
+- `constants.ESC`
+- `constants.CSI`
+- `constants.SGR(n)`
+
+### Cursor Controls
+
+- `cursorHide`, `cursorShow`
+- `cursorUp(n)`, `cursorDown(n)`, `cursorForward(n)`, `cursorBack(n)`
+- `cursorNextLine(n)`, `cursorPreviousLine(n)`
+- `cursorPosition(column[, row])`
+
+### Erase Controls
+
+- `eraseDisplayEnd`, `eraseDisplayStart`, `eraseDisplay`
+- `eraseLineEnd`, `eraseLineStart`, `eraseLine`
+
+### Scrolling
+
+- `scrollUp(n)`, `scrollDown(n)`
+
+### Styling (SGR)
+
+- Modifiers: `modifierReset`, `modifierBold`, `modifierDim`, `modifierItalic`, `modifierUnderline`, `modifierNormal`, `modifierNotItalic`, `modifierNotUnderline`
+- Colors: `colorRed`, `colorGreen`, `colorYellow`, `colorBlue`, `colorMagenta`, `colorCyan`, `colorWhite`, `colorDefault`, plus bright variants.
+
+## Complete Examples
+
+### Example 1: Clear Screen
+
+```js
+const ansi = require('bare-ansi-escapes')
+
+process.stdout.write(ansi.eraseDisplay + ansi.cursorPosition(0, 0))
+```
+
+### Example 2: Styled Output
+
+```js
+const ansi = require('bare-ansi-escapes')
+
+process.stdout.write(ansi.colorGreen + 'OK' + ansi.modifierReset)
+```
+
+### Example 3: Cursor Movement
+
+```js
+const ansi = require('bare-ansi-escapes')
+
+process.stdout.write(ansi.cursorUp(2))
+```
+
+### Example 4: Key Decoder
+
+```js
+const KeyDecoder = require('bare-ansi-escapes/key-decoder')
+
+process.stdin.pipe(new KeyDecoder()).on('data', (key) => {
+  console.log(key)
+})
+```
+
+## Best Practices
+
+- **Always reset styles** after applying SGR codes.
+- **Guard ANSI** when output is not a TTY.
+
+## Performance Notes
+
+- String concatenation is cheap; IO is the dominant cost.
+
+## Security Considerations
+
+- Avoid injecting untrusted strings into ANSI output if logs are consumed by terminals.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Utility | **Ecosystem Role**: Terminal Control | **Dependencies**: None

modules/bare-apk.md

@@ -0,0 +1,155 @@
+# bare-apk
+
+APK packaging utilities for Bare. Wraps Android tooling (`aapt2`, `bundletool`) to produce `.aab` bundles, `.apks` sets, and `.apk` outputs.
+
+## Install
+
+```bash
+npm i bare-apk
+```
+
+## Overview
+
+- Creates Android App Bundles from a manifest and resources.
+- Builds APK sets and extracts universal APKs.
+- Supports signing via keystore configuration.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  A[AndroidManifest.xml] --> B[createAppBundle]
+  C[res/ & assets] --> B
+  B --> D[.aab]
+  D --> E[createAPKSet]
+  E --> F[.apks (zip or dir)]
+  F --> G[createAPK]
+  G --> H[universal.apk]
+```
+
+## API
+
+#### `await createAppBundle(manifest, out[, options])`
+
+Options:
+
+```js
+{
+  targetSDK: DEFAULT_TARGET_SDK,
+  include: [],        // additional files/dirs to include uncompressed
+  resources           // resource directory to compile
+}
+```
+
+#### `await createAPKSet(bundle, out[, options])`
+
+Options:
+
+```js
+{
+  universal: false,
+  archive: true,
+  sign: false,
+  keystore,
+  keystoreKey,
+  keystorePassword
+}
+```
+
+#### `await createAPK(bundle, out[, options])`
+
+Options:
+
+```js
+{
+  sign: false,
+  keystore,
+  keystoreKey,
+  keystorePassword
+}
+```
+
+#### `constants`
+
+```js
+{
+  ANDROID_HOME,
+  DEFAULT_MINIMUM_SDK,
+  DEFAULT_TARGET_SDK
+}
+```
+
+## Examples
+
+### 1) Create an app bundle
+
+```js
+const { createAppBundle } = require('bare-apk')
+
+await createAppBundle('./AndroidManifest.xml', './dist/app.aab', {
+  resources: './android-res'
+})
+```
+
+### 2) Build an APK set (directory output)
+
+```js
+const { createAPKSet } = require('bare-apk')
+
+await createAPKSet('./dist/app.aab', './dist/apks', {
+  archive: false,
+  universal: true
+})
+```
+
+### 3) Generate a universal APK
+
+```js
+const { createAPK } = require('bare-apk')
+
+await createAPK('./dist/app.aab', './dist/app.apk')
+```
+
+### 4) Signed APKs
+
+```js
+const { createAPKSet } = require('bare-apk')
+
+await createAPKSet('./dist/app.aab', './dist/app.apks', {
+  sign: true,
+  keystore: './keys/release.jks',
+  keystoreKey: 'release',
+  keystorePassword: 'env:KEYSTORE_PASS'
+})
+```
+
+## Best Practices
+
+- Set `ANDROID_HOME` to a stable Android SDK path in CI.
+- Use explicit `targetSDK` to avoid toolchain drift.
+- Keep keystore material out of source control and inject via env.
+- For reproducible builds, pin the `bundletool`/`aapt2` versions in `prebuilds/`.
+
+## Performance Notes
+
+- `aapt2` and `bundletool` can be CPU heavy; prefer CI runners with adequate cores.
+- Large resource trees benefit from incremental rebuilds and caching.
+
+## Security Considerations
+
+- Treat keystore passwords as secrets; use CI secret stores.
+- Validate resource inputs to avoid bundling unexpected files.
+
+## Integration Notes
+
+- Works with Bare build pipelines (`bare-app-kit`, `bare-distributable`).
+- Pair with `bare-app-image` for Linux distributions in multi-platform releases.
+
+## Error Handling
+
+- Errors bubble from Java tool invocations; capture stderr for diagnostics.
+- If `ANDROID_HOME` is missing or invalid, app bundle creation will fail.
+
+## License
+
+Apache-2.0

modules/bare-app-image.md

@@ -0,0 +1,101 @@
+# bare-app-image
+
+AppImage packaging tools for Bare. Wraps `appimagetool` to turn an `AppDir` into a distributable `.AppImage`.
+
+## Install
+
+```bash
+npm i bare-app-image
+```
+
+## Overview
+
+- Linux-only packaging utility.
+- Accepts an AppDir tree and writes an AppImage.
+- Optional compression and signing.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  A[AppDir] --> B[createAppImage]
+  B --> C[appimagetool]
+  C --> D[.AppImage]
+```
+
+## API
+
+#### `await createAppImage(source[, destination][, options])`
+
+Options:
+
+```js
+{
+  compression,   // e.g. 'xz', 'gzip'
+  sign: false,
+  key            // signing key path
+}
+```
+
+## Examples
+
+### 1) Basic AppImage creation
+
+```js
+const { createAppImage } = require('bare-app-image')
+
+await createAppImage('./dist/MyApp.AppDir', './dist/MyApp.AppImage')
+```
+
+### 2) Compression enabled
+
+```js
+await createAppImage('./dist/MyApp.AppDir', './dist/MyApp.AppImage', {
+  compression: 'xz'
+})
+```
+
+### 3) Signed AppImage
+
+```js
+await createAppImage('./dist/MyApp.AppDir', './dist/MyApp.AppImage', {
+  sign: true,
+  key: './keys/appimage.pem'
+})
+```
+
+### 4) Destination omitted
+
+```js
+await createAppImage('./dist/MyApp.AppDir')
+```
+
+## Best Practices
+
+- Ensure AppDir includes a valid `AppRun` and `.desktop` entry.
+- Keep AppDir minimal to reduce AppImage size.
+- Use reproducible builds by pinning tool versions in CI.
+
+## Performance Notes
+
+- Compression trades time for smaller artifacts; pick based on release channel.
+- Large AppDirs may need CI workers with sufficient disk I/O.
+
+## Security Considerations
+
+- Keep signing keys in secret storage and only sign in trusted CI.
+- Verify AppDir contents to avoid shipping unintended binaries.
+
+## Integration Notes
+
+- Often used alongside `bare-distributable` or release tooling.
+- Pair with `bare-apk` for Android distributions.
+
+## Error Handling
+
+- Errors surface from `appimagetool`; capture stderr for diagnostics.
+- Linux-only: on non-Linux, the package cannot run the toolchain.
+
+## License
+
+Apache-2.0

modules/bare-app-kit.md

@@ -0,0 +1,164 @@
+# bare-app-kit
+
+AppKit bindings and runtime for Bare on macOS. Exposes a `Window` class backed by native AppKit and a small runtime helper for prebuilt Bare binaries.
+
+## Install
+
+```bash
+npm i bare-app-kit
+```
+
+## Overview
+
+- macOS-only AppKit windowing API for Bare apps.
+- Native addon with a JS wrapper and event emitter interface.
+- Includes `runtime.js` with prebuilt Bare binary helpers.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  A[App JS] --> B[Window class]
+  B --> C[binding.m / native AppKit]
+  B --> D[bare-events]
+  E[runtime.js] --> F[prebuilds/darwin-*]
+```
+
+## API
+
+#### `const { Window } = require('bare-app-kit')`
+
+#### `new Window(options)`
+
+Options:
+
+```js
+{
+  x: 0,
+  y: 0,
+  width: 0,
+  height: 0,
+  styleMask: 0,
+  defer: false
+}
+```
+
+#### `window.contentView`
+
+Get/set the window content view.
+
+#### `window.titlebarAppearsTransparent`
+
+Get/set titlebar transparency.
+
+#### `window.center()`
+
+Center the window on screen. Returns `this`.
+
+#### `window.close()`
+
+Close the window. Returns `this`.
+
+#### `window.makeKeyWindow()`
+
+Make window the key window. Returns `this`.
+
+#### `window.orderFront()` / `window.orderBack()`
+
+Adjust window z-order. Returns `this`.
+
+#### Events
+
+- `did-resize`
+- `did-move`
+- `will-close`
+
+#### `Window.STYLE_MASK`
+
+```js
+{
+  BORDERLESS,
+  TITLED,
+  CLOSABLE,
+  MINIATURIZABLE,
+  RESIZABLE,
+  FULL_SCREEN,
+  FULL_SIZE_CONTENT_VIEW
+}
+```
+
+#### `require('bare-app-kit/runtime')`
+
+Exports `prebuilds` helpers for locating Bare binaries:
+
+```js
+const { prebuilds } = require('bare-app-kit/runtime')
+const barePath = prebuilds['darwin-arm64']()
+```
+
+## Examples
+
+### 1) Create a window
+
+```js
+const { Window } = require('bare-app-kit')
+
+const win = new Window({ width: 800, height: 600 })
+win.center().makeKeyWindow()
+```
+
+### 2) Custom titlebar
+
+```js
+const { Window } = require('bare-app-kit')
+
+const win = new Window({ width: 640, height: 480 })
+win.titlebarAppearsTransparent = true
+```
+
+### 3) Window event handling
+
+```js
+win.on('did-resize', () => console.log('resized'))
+win.on('will-close', () => console.log('closing'))
+```
+
+### 4) Use style masks
+
+```js
+const { Window } = require('bare-app-kit')
+
+const win = new Window({
+  width: 400,
+  height: 300,
+  styleMask: Window.STYLE_MASK.TITLED | Window.STYLE_MASK.RESIZABLE
+})
+```
+
+## Best Practices
+
+- Instantiate windows after the app/runtime is initialized.
+- Use style masks intentionally; avoid unsupported combinations.
+- Dispose windows explicitly to avoid native resource leaks.
+
+## Performance Notes
+
+- UI performance is native; heavy JS work should be moved off the main thread.
+
+## Security Considerations
+
+- Treat native bindings as trusted; only load prebuilds from verified sources.
+
+## Integration Notes
+
+- Works with `bare-web-kit` or custom render layers.
+- Use `bare-app-kit/runtime` to bundle a Bare runtime with apps.
+
+## Error Handling
+
+- Native exceptions surface as JS errors; wrap window creation in try/catch.
+- Some APIs are macOS-only and will fail on other platforms.
+
+## License
+
+Apache-2.0

modules/bare-assert.md

@@ -0,0 +1,132 @@
+# bare-assert - Assertion Utilities
+
+## Overview
+
+bare-assert provides a minimal assertion library with a Node-like API. It includes `AssertionError` and common assertion helpers such as `ok`, `equal`, and `strictEqual`.
+
+### Key Features
+
+- **Small surface**: Core assertion helpers only.
+- **Readable errors**: Uses `bare-inspect` for message formatting.
+- **AssertionError**: Standard error type with `actual`, `expected`, `operator`.
+
+### Use Cases
+
+- **Tests**: Simple assertion checks without full test frameworks.
+- **Runtime guards**: Validate invariants in Bare apps.
+
+## Installation
+
+```bash
+npm install bare-assert
+```
+
+## Quick Start
+
+```js
+const assert = require('bare-assert')
+
+assert.ok(1 + 1 === 2)
+```
+
+## API Reference
+
+### `const assert = require('bare-assert')`
+
+Main function behaves like `assert.ok`.
+
+### `assert(actual[, message])`
+### `assert.ok(actual[, message])`
+
+Throw if `actual` is falsy.
+
+### `assert.notOk(actual[, message])`
+
+Throw if `actual` is truthy.
+
+### `assert.equal(actual, expected[, message])`
+
+Loose equality with `==` semantics plus NaN handling.
+
+### `assert.notEqual(actual, expected[, message])`
+
+Loose inequality.
+
+### `assert.strictEqual(actual, expected[, message])`
+
+Strict equality via `Object.is`.
+
+### `assert.notStrictEqual(actual, expected[, message])`
+
+Strict inequality.
+
+### `assert.fail([message])`
+
+Always throws.
+
+### `assert.AssertionError`
+
+Custom error type for assertion failures.
+
+## Complete Examples
+
+### Example 1: Basic Assertions
+
+```js
+const assert = require('bare-assert')
+
+assert(2 + 2 === 4)
+assert.ok(true)
+```
+
+### Example 2: Equality Checks
+
+```js
+const assert = require('bare-assert')
+
+assert.equal('1', 1)
+assert.strictEqual(1, 1)
+```
+
+### Example 3: Not Equal
+
+```js
+const assert = require('bare-assert')
+
+assert.notEqual(1, 2)
+assert.notStrictEqual(1, '1')
+```
+
+### Example 4: Custom Fail
+
+```js
+const assert = require('bare-assert')
+
+assert.fail('Unexpected path')
+```
+
+## Best Practices
+
+- **Provide messages** for easier debugging.
+- **Use strictEqual** when type correctness matters.
+
+## Performance Notes
+
+- Assertions are lightweight; avoid in hot paths in production if needed.
+
+## Integration with Other Modules
+
+### With bare-inspect
+
+Error messages use `bare-inspect` to render values.
+
+## Error Handling
+
+- Throws `AssertionError` on failure.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Utility | **Ecosystem Role**: Assertions | **Dependencies**: bare-inspect

modules/bare-async-hooks.md

@@ -0,0 +1,109 @@
+# bare-async-hooks - async_hooks Shim
+
+## Overview
+
+bare-async-hooks provides a minimal `async_hooks` shim for the Bare runtime. It offers API-compatible entry points but most hooks are no-ops and async resource methods are not implemented.
+
+### Key Features
+
+- **API compatibility**: Exposes `createHook`, `executionAsyncId`, and `AsyncResource`.
+- **No-op hooks**: Hook methods are present but do nothing.
+- **Safe fallbacks**: Returns `-1` for async IDs.
+
+### Use Cases
+
+- **Dependency compatibility**: Satisfy libraries expecting `async_hooks`.
+- **Graceful degradation**: Provide stub behavior in Bare.
+
+## Installation
+
+```bash
+npm install bare-async-hooks
+```
+
+## Quick Start
+
+```js
+const asyncHooks = require('bare-async-hooks')
+
+const hook = asyncHooks.createHook({})
+hook.enable()
+```
+
+## API Reference
+
+### `createHook(opts) -> AsyncHook`
+
+Returns a hook with `enable()` and `disable()` methods (no-op).
+
+### `executionAsyncId() -> number`
+### `triggerAsyncId() -> number`
+
+Always returns `-1` in this shim.
+
+### `AsyncResource`
+
+Class with methods:
+
+- `bind()` / `AsyncResource.bind()` (throws `Not implemented`)
+- `runInAsyncScope()` (throws)
+- `emitDestroy()` (throws)
+- `asyncId()` (returns `-1`)
+- `triggerAsyncId()` (returns `-1`)
+
+## Complete Examples
+
+### Example 1: Create Hook
+
+```js
+const { createHook } = require('bare-async-hooks')
+
+createHook({ init() {}, destroy() {} }).enable()
+```
+
+### Example 2: Async IDs
+
+```js
+const { executionAsyncId } = require('bare-async-hooks')
+
+console.log(executionAsyncId()) // -1
+```
+
+### Example 3: AsyncResource Stub
+
+```js
+const { AsyncResource } = require('bare-async-hooks')
+
+const res = new AsyncResource()
+console.log(res.asyncId())
+```
+
+## Best Practices
+
+- **Use for compatibility only**; behavior is not equivalent to Node.
+- **Avoid AsyncResource methods** that throw in Bare.
+
+## Performance Notes
+
+- Negligible overhead; most operations are no-ops.
+
+## Security Considerations
+
+- None specific; this is a stub module.
+
+## Integration with Other Modules
+
+### With Node-targeted libraries
+
+Use to satisfy optional async hook dependencies when running under Bare.
+
+## Error Handling
+
+- Some `AsyncResource` methods throw `Not implemented`.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Shim | **Ecosystem Role**: Compatibility | **Dependencies**: None

modules/bare-atomics.md

@@ -0,0 +1,170 @@
+# bare-atomics - Native Synchronization Primitives
+
+## Overview
+
+bare-atomics exposes native synchronization primitives for JavaScript in the Bare runtime. It provides `Mutex`, `Semaphore`, `Condition`, and `Barrier` implemented with native handles stored in `SharedArrayBuffer`.
+
+### Key Features
+
+- **Native mutexes**: Recursive or non-recursive locks.
+- **Semaphores**: Wait/post semantics.
+- **Conditions**: Wait/signal/broadcast with mutex integration.
+- **Barriers**: Wait until a set count is reached.
+
+### Use Cases
+
+- **Thread coordination**: Manage worker synchronization.
+- **Shared memory workflows**: Combine with `SharedArrayBuffer`.
+- **Low-level concurrency**: Implement safe critical sections.
+
+## Installation
+
+```bash
+npm install bare-atomics
+```
+
+## Quick Start
+
+```js
+const { Mutex } = require('bare-atomics')
+
+const mutex = new Mutex()
+mutex.lock()
+// critical section
+mutex.unlock()
+```
+
+## API Reference
+
+### `new Mutex([opts])`
+
+Options:
+
+- `recursive` (boolean): Allow re-locking (default false).
+
+Properties:
+
+- `mutex.handle` (SharedArrayBuffer)
+- `mutex.held` (boolean)
+
+Methods:
+
+- `lock()`
+- `tryLock() -> boolean`
+- `unlock()`
+- `destroy()`
+- `Mutex.from(handle, opts)`
+
+### `new Semaphore(value)`
+
+Properties:
+
+- `semaphore.handle` (SharedArrayBuffer)
+
+Methods:
+
+- `wait()`
+- `tryWait() -> boolean`
+- `post()`
+- `destroy()`
+- `Semaphore.from(handle)`
+
+### `new Condition()`
+
+Properties:
+
+- `condition.handle` (SharedArrayBuffer)
+
+Methods:
+
+- `wait(mutex[, timeout]) -> boolean`
+- `signal()`
+- `broadcast()`
+- `destroy()`
+- `Condition.from(handle)`
+
+### `new Barrier(count)`
+
+Properties:
+
+- `barrier.handle` (SharedArrayBuffer)
+
+Methods:
+
+- `wait() -> boolean`
+- `destroy()`
+- `Barrier.from(handle)`
+
+## Complete Examples
+
+### Example 1: Mutex Guard
+
+```js
+const { Mutex } = require('bare-atomics')
+
+const mutex = new Mutex()
+mutex.lock()
+try {
+  // critical section
+} finally {
+  mutex.unlock()
+}
+```
+
+### Example 2: Semaphore
+
+```js
+const { Semaphore } = require('bare-atomics')
+
+const sem = new Semaphore(1)
+sem.wait()
+// do work
+sem.post()
+```
+
+### Example 3: Condition Wait
+
+```js
+const { Mutex, Condition } = require('bare-atomics')
+
+const mutex = new Mutex()
+const cond = new Condition()
+
+mutex.lock()
+cond.wait(mutex)
+mutex.unlock()
+```
+
+### Example 4: Barrier
+
+```js
+const { Barrier } = require('bare-atomics')
+
+const barrier = new Barrier(4)
+barrier.wait()
+```
+
+## Best Practices
+
+- **Always unlock** mutexes in `finally` blocks.
+- **Destroy handles** when finished to free resources.
+- **Avoid double-lock** for non-recursive mutexes.
+
+## Performance Notes
+
+- Native primitives are fast; contention can still be costly.
+
+## Security Considerations
+
+- Ensure correct lock usage to avoid deadlocks.
+
+## Error Handling
+
+- Throws on invalid lock/unlock usage (e.g., unlock unheld mutex).
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Concurrency | **Ecosystem Role**: Synchronization | **Dependencies**: native binding

modules/bare-bmp.md

@@ -0,0 +1,117 @@
+# bare-bmp
+
+Native BMP codec for Bare. Decodes BMP buffers to RGBA and encodes RGBA back to BMP.
+
+## Install
+
+```bash
+npm i bare-bmp
+```
+
+## Overview
+
+- Native addon for fast BMP encode/decode.
+- Works with Node buffers and returns RGBA data.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  A[BMP Buffer] --> B[decode]
+  B --> C[{width,height,data}]
+  C --> D[encode]
+  D --> E[BMP Buffer]
+```
+
+## API
+
+#### `const bmp = require('bare-bmp')`
+
+#### `bmp.decode(buffer)`
+
+Returns:
+
+```js
+{ width, height, data } // data is a Buffer (RGBA)
+```
+
+#### `bmp.encode(image[, options])`
+
+```js
+{ width, height, data } // data is Buffer or Uint8Array (RGBA)
+```
+
+Returns a BMP `Buffer`.
+
+#### `bmp.encodeAnimated()`
+
+Placeholder for animated encoding (delegates to native binding).
+
+## Examples
+
+### 1) Decode a BMP
+
+```js
+const fs = require('fs')
+const bmp = require('bare-bmp')
+
+const buf = fs.readFileSync('./image.bmp')
+const { width, height, data } = bmp.decode(buf)
+```
+
+### 2) Encode RGBA to BMP
+
+```js
+const bmp = require('bare-bmp')
+
+const image = { width: 2, height: 2, data: Buffer.from([255, 0, 0, 255, 0, 0, 255, 255, 0, 255, 0, 255, 255, 255, 255, 255]) }
+const out = bmp.encode(image)
+```
+
+### 3) Round-trip transform
+
+```js
+const bmp = require('bare-bmp')
+
+const decoded = bmp.decode(input)
+// mutate decoded.data (RGBA)
+const output = bmp.encode(decoded)
+```
+
+### 4) Stream pipeline
+
+```js
+const chunks = []
+stream.on('data', chunk => chunks.push(chunk))
+stream.on('end', () => {
+  const bmpBuf = Buffer.concat(chunks)
+  const img = bmp.decode(bmpBuf)
+  // ...process...
+})
+```
+
+## Best Practices
+
+- Ensure `data.length === width * height * 4` for RGBA.
+- Avoid per-pixel JS loops for large images; batch operations.
+
+## Performance Notes
+
+- Native decoding is fast; avoid copying `data` unnecessarily.
+- Use Buffers rather than arrays for large images.
+
+## Security Considerations
+
+- Treat BMP inputs as untrusted; guard against oversized dimensions.
+
+## Integration Notes
+
+- Pair with `bare-image-resample` or `bare-png` for format conversions.
+
+## Error Handling
+
+- Invalid BMP data throws from native binding; wrap decode in try/catch.
+
+## License
+
+Apache-2.0

modules/bare-bundle-compile.md

@@ -0,0 +1,90 @@
+# bare-bundle-compile - Compile Bundles to a Single Module
+
+## Overview
+
+bare-bundle-compile turns a `bare-bundle` into a single CommonJS module string. It is intended for environments without a module system, producing self-contained code that can be `eval`'d.
+
+### Key Features
+
+- **Single-file output**: Produces a standalone module string.
+- **Builtin support**: Uses `builtin:` specifiers when present.
+- **Addon/asset support**: Resolves `addon` and `asset` entries.
+
+### Use Cases
+
+- **Bootstrap environments**: Execute bundles with minimal runtime support.
+- **Sandbox execution**: Evaluate bundles in restricted environments.
+
+## Installation
+
+```bash
+npm install bare-bundle-compile
+```
+
+## Quick Start
+
+```js
+const Bundle = require('bare-bundle')
+const compile = require('bare-bundle-compile')
+
+const bundle = new Bundle().write('/main.js', 'module.exports = 42', { main: true })
+const code = compile(bundle)
+const mod = eval(code)
+```
+
+## API Reference
+
+### `compile(bundle) -> string`
+
+Returns a string containing a self-contained module loader and module sources.
+
+## Complete Examples
+
+### Example 1: Evaluate Bundle
+
+```js
+const Bundle = require('bare-bundle')
+const compile = require('bare-bundle-compile')
+
+const bundle = new Bundle()
+  .write('/foo.js', "module.exports = require('./bar')", { main: true, imports: { './bar': '/bar.js' } })
+  .write('/bar.js', 'module.exports = 42')
+
+const result = eval(compile(bundle)).exports
+```
+
+### Example 2: JSON Module
+
+```js
+const Bundle = require('bare-bundle')
+const compile = require('bare-bundle-compile')
+
+const bundle = new Bundle().write('/data.json', '{"a":1}', { main: true })
+eval(compile(bundle))
+```
+
+### Example 3: Asset Resolution
+
+```js
+const Bundle = require('bare-bundle')
+const compile = require('bare-bundle-compile')
+
+const bundle = new Bundle().write('/main.js', 'module.exports = require.asset("./file.txt")', { main: true })
+eval(compile(bundle))
+```
+
+## Best Practices
+
+- **Use only in minimal environments**; for general runtimes use `bare-bundle-evaluate`.
+- **Ensure `bundle.main` is set** for correct startup.
+
+## Performance Notes
+
+- Compilation is a string build; runtime cost is in eval and module loading.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Tooling | **Ecosystem Role**: Bundle Compiler | **Dependencies**: bare-bundle

modules/bare-bundle-evaluate.md

@@ -0,0 +1,89 @@
+# bare-bundle-evaluate - Evaluate Bundles Across Runtimes
+
+## Overview
+
+bare-bundle-evaluate runs a `bare-bundle` in a CommonJS-compatible environment. It supports builtins, addon resolution, and runtime-specific extensions, making it a more general solution than `bare-bundle-compile`.
+
+### Key Features
+
+- **Cross-runtime**: Works across JS runtimes with a configurable runtime descriptor.
+- **Addon support**: Resolves native addons with `bare-addon-resolve`.
+- **Builtin resolution**: `builtin:` protocol support.
+
+### Use Cases
+
+- **Bundle execution**: Run bundles in Node or Bare-like runtimes.
+- **Testing**: Execute bundled code in CI.
+
+## Installation
+
+```bash
+npm install bare-bundle-evaluate
+```
+
+## Quick Start
+
+```js
+const Bundle = require('bare-bundle')
+const evaluate = require('bare-bundle-evaluate')
+
+const bundle = new Bundle()
+  .write('/main.js', 'module.exports = 42', { main: true })
+
+const mod = evaluate(bundle)
+console.log(mod.exports)
+```
+
+## API Reference
+
+### `evaluate(bundle[, runtime][, builtinRequire])`
+
+- `runtime`: runtime descriptor (defaults to internal runtime).
+- `builtinRequire`: override builtin require.
+
+Returns a CommonJS-like module object with `exports`.
+
+## Complete Examples
+
+### Example 1: Evaluate Bundle
+
+```js
+const Bundle = require('bare-bundle')
+const evaluate = require('bare-bundle-evaluate')
+
+const bundle = new Bundle().write('/main.js', 'module.exports = 42', { main: true })
+console.log(evaluate(bundle).exports)
+```
+
+### Example 2: Use Custom Runtime
+
+```js
+const evaluate = require('bare-bundle-evaluate')
+
+const runtime = { host: 'linux-x64', builtins: [], extensions: { module: ['.js'], addon: ['.node'] }, versions: {}, conditions: [] }
+evaluate(bundle, runtime)
+```
+
+### Example 3: Builtin Require
+
+```js
+const evaluate = require('bare-bundle-evaluate')
+
+evaluate(bundle, null, require)
+```
+
+## Best Practices
+
+- **Use `bare-bundle-compile`** only for runtimes without a module system.
+- **Provide runtime extensions** to match your target platform.
+
+## Performance Notes
+
+- Evaluation cost depends on bundle size and IO for addons/assets.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Runtime Utility | **Ecosystem Role**: Bundle Evaluation | **Dependencies**: bare-module-resolve, bare-addon-resolve

modules/bare-bundle-id.md

@@ -0,0 +1,79 @@
+# bare-bundle-id - Bundle Hashing
+
+## Overview
+
+bare-bundle-id computes a deterministic hash for a `bare-bundle`. It hashes file paths, contents, and modes to generate a 32-byte identifier.
+
+### Key Features
+
+- **Deterministic**: Same bundle yields same ID.
+- **Content-aware**: Includes file contents and modes.
+
+### Use Cases
+
+- **Cache keys**: Identify bundles in build pipelines.
+- **Integrity checks**: Compare bundle versions.
+
+## Installation
+
+```bash
+npm install bare-bundle-id
+```
+
+## Quick Start
+
+```js
+const Bundle = require('bare-bundle')
+const id = require('bare-bundle-id')
+
+const bundle = new Bundle().write('/main.js', 'module.exports = 1', { main: true })
+const hash = id(bundle).toString('hex')
+```
+
+## API Reference
+
+### `id(bundle[, out]) -> Buffer`
+
+Returns a buffer containing the hash. `out` can be provided to reuse a buffer.
+
+## Complete Examples
+
+### Example 1: Generate ID
+
+```js
+const id = require('bare-bundle-id')
+
+const hash = id(bundle)
+```
+
+### Example 2: Hex String
+
+```js
+const id = require('bare-bundle-id')
+
+const hex = id(bundle).toString('hex')
+```
+
+### Example 3: Compare Bundles
+
+```js
+const id = require('bare-bundle-id')
+
+if (id(a).equals(id(b))) console.log('same')
+```
+
+## Best Practices
+
+- **Sort bundle contents** before hashing (handled internally).
+- **Use for caching** to avoid unnecessary rebuilds.
+
+## Performance Notes
+
+- Hashing cost scales with bundle size.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Tooling | **Ecosystem Role**: Bundle Identity | **Dependencies**: sodium-native

modules/bare-compat-napi.md

@@ -0,0 +1,67 @@
+# bare-compat-napi - Node-API Compatibility Headers
+
+## Overview
+
+bare-compat-napi provides compatibility headers for Node-API (N-API) when building native addons for the Bare runtime. It ships `include/` headers and CMake integration for building against Bare.
+
+### Key Features
+
+- **Header-only distribution**: Ships `include/` directory.
+- **N-API compatibility**: Facilitates porting Node-API addons.
+- **CMake integration**: Works with `cmake-napi` and `cmake-fetch`.
+
+### Use Cases
+
+- **Port N-API addons** to Bare.
+- **Native build toolchains** requiring N-API symbols.
+
+## Installation
+
+```bash
+npm install bare-compat-napi
+```
+
+## Usage
+
+Include headers from `node_modules/bare-compat-napi/include` in your build system.
+
+```cmake
+include_directories(${CMAKE_CURRENT_LIST_DIR}/node_modules/bare-compat-napi/include)
+```
+
+## Complete Examples
+
+### Example 1: CMake Include
+
+```cmake
+include_directories(${PROJECT_SOURCE_DIR}/node_modules/bare-compat-napi/include)
+```
+
+### Example 2: cmake-napi
+
+```cmake
+find_package(cmake-napi REQUIRED)
+```
+
+### Example 3: Build Tests
+
+```bash
+cmake -S . -B build
+cmake --build build
+```
+
+## Best Practices
+
+- **Pin versions** with your Bare runtime version.
+- **Use cmake-napi** for consistent build behavior.
+
+## Performance Notes
+
+- Build-time only; no runtime overhead.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Build Tool | **Ecosystem Role**: N-API Compatibility | **Dependencies**: None

modules/bare-console.md

@@ -0,0 +1,118 @@
+# bare-console - WHATWG Console Implementation
+
+## Overview
+
+bare-console provides a WHATWG-compatible `Console` implementation for Bare. It supports `log`, `info`, `warn`, `error`, timers, counters, and tracing. A custom backend can be supplied (e.g., file logger).
+
+### Key Features
+
+- **WHATWG Console API**: `log`, `info`, `warn`, `error`, `trace`, `assert`.
+- **Timers and counters**: `time`, `timeLog`, `timeEnd`, `count`, `countReset`.
+- **Custom backend**: Plug in `bare-file-logger` or other logger implementations.
+
+### Use Cases
+
+- **App logging**: Provide standard console output in Bare.
+- **Persistent logs**: Route logs to files or system log.
+- **Debugging**: Trace stack or measure performance.
+
+## Installation
+
+```bash
+npm install bare-console
+```
+
+## Quick Start
+
+```js
+const Console = require('bare-console')
+
+const console = new Console()
+console.log('Hello')
+```
+
+## API Reference
+
+### `new Console([backend])`
+
+**Parameters:**
+- `backend` (object, optional): Logger implementing `debug/info/warn/error/clear/format`.
+
+### Methods
+
+- `debug`, `info`, `warn`, `error`, `log`
+- `clear`
+- `time(label)`, `timeLog(label, ...data)`, `timeEnd(label)`
+- `count(label)`, `countReset(label)`
+- `trace(...data)`
+- `assert(condition, ...data)`
+
+## Complete Examples
+
+### Example 1: Basic Console
+
+```js
+const Console = require('bare-console')
+
+const console = new Console()
+console.info('ready')
+```
+
+### Example 2: Timers
+
+```js
+const Console = require('bare-console')
+
+const console = new Console()
+console.time('task')
+// do work
+console.timeEnd('task')
+```
+
+### Example 3: Counters
+
+```js
+const Console = require('bare-console')
+
+const console = new Console()
+console.count('loop')
+console.count('loop')
+console.countReset('loop')
+```
+
+### Example 4: File Logger Backend
+
+```js
+const Console = require('bare-console')
+const FileLog = require('bare-file-logger')
+
+const log = new FileLog('app.log')
+const console = new Console(log)
+console.error(new Error('fail'))
+```
+
+## Best Practices
+
+- **Use a backend** when you need structured or persistent logs.
+- **Avoid heavy logging** in hot paths.
+
+## Performance Notes
+
+- Logging overhead depends on backend; timers use `bare-hrtime`.
+
+## Security Considerations
+
+- Avoid logging sensitive data to persistent backends.
+
+## Integration with Other Modules
+
+### With bare-logger / bare-file-logger
+
+Use as backends for formatted output and file logging.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Runtime Utility | **Ecosystem Role**: Logging | **Dependencies**: bare-logger, bare-hrtime

modules/bare-cov.md

@@ -0,0 +1,99 @@
+# bare-cov
+
+Coverage capture utility for Bare and Node.js using V8 Inspector. Attaches at runtime, records coverage, and emits reports on process exit.
+
+## Install
+
+```bash
+npm i bare-cov
+```
+
+## Overview
+
+- Starts V8 precise coverage and writes reports on `beforeExit`.
+- Generates `v8-coverage.json` and reporter outputs (text/json by default).
+- Works in Bare and Node with a unified API.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  A[require('bare-cov')] --> B[Inspector Session]
+  B --> C[Profiler.startPreciseCoverage]
+  C --> D[beforeExit hook]
+  D --> E[v8-coverage.json]
+  D --> F[Transformer -> reports]
+```
+
+## API
+
+#### `const setupCoverage = require('bare-cov')`
+
+#### `await setupCoverage(options)`
+
+Options:
+
+```js
+{
+  reporters: ['text', 'json'],
+  reporterOptions: {},
+  dir: 'coverage',
+  skipRawDump: false
+}
+```
+
+## Examples
+
+### 1) Basic usage
+
+```js
+require('bare-cov')()
+// run tests; reports are generated on exit
+```
+
+### 2) Custom output directory
+
+```js
+require('bare-cov')({ dir: './artifacts/coverage' })
+```
+
+### 3) JSON only
+
+```js
+require('bare-cov')({ reporters: ['json'] })
+```
+
+### 4) Skip raw dump
+
+```js
+require('bare-cov')({ skipRawDump: true })
+```
+
+## Best Practices
+
+- Require `bare-cov` at the top of your test entrypoint.
+- Keep `reporters` minimal in CI to reduce file churn.
+- Use a dedicated `coverage/` dir to avoid polluting the repo root.
+
+## Performance Notes
+
+- Precise coverage adds runtime overhead; avoid in production builds.
+- Large test suites generate large JSON; ensure enough disk space.
+
+## Security Considerations
+
+- Coverage output may include source paths; treat artifacts as sensitive in CI.
+
+## Integration Notes
+
+- Compatible with `brittle` and Bare test harnesses.
+- Pairs with `bare-v8-to-istanbul` for Istanbul-compatible reports.
+
+## Error Handling
+
+- Inspector session errors reject; wrap in try/catch if needed.
+- If `beforeExit` does not fire (hard crash), reports may be missing.
+
+## License
+
+Apache-2.0

modules/bare-diagnostics-channel.md

@@ -0,0 +1,134 @@
+# bare-diagnostics-channel - Diagnostics Channels
+
+## Overview
+
+bare-diagnostics-channel implements named diagnostics channels similar to Node's `diagnostics_channel`. It supports publishing events, subscribing/unsubscribing, and tracing channels for start/end/error events.
+
+### Key Features
+
+- **Named channels**: Create or retrieve channels by name.
+- **Publish/subscribe**: Send arbitrary data to subscribers.
+- **Tracing channels**: `tracingChannel(name)` with start/end/error.
+- **Safe errors**: Subscriber errors are rethrown asynchronously.
+
+### Use Cases
+
+- **Instrumentation**: Observe internal events without hard dependencies.
+- **Diagnostics**: Capture runtime metrics or traces.
+- **Pluggable hooks**: Let libraries emit optional events.
+
+## Installation
+
+```bash
+npm install bare-diagnostics-channel
+```
+
+## Quick Start
+
+```js
+const dc = require('bare-diagnostics-channel')
+
+const ch = dc.channel('my:event')
+ch.subscribe((data) => console.log(data))
+ch.publish({ ok: true })
+```
+
+## API Reference
+
+### `channel(name) -> Channel`
+
+Get or create a channel.
+
+### `subscribe(name, fn)` / `unsubscribe(name, fn)`
+
+Convenience helpers for named channels.
+
+### `hasSubscribers(name) -> boolean`
+
+Check if a channel has any subscribers.
+
+### `class Channel`
+
+- `name`
+- `hasSubscribers`
+- `subscribe(fn)`
+- `unsubscribe(fn)`
+- `publish(data)`
+
+### `tracingChannel(nameOrChannels) -> TracingChannel`
+
+Returns a tracing channel with `start`, `end`, and `error` subchannels.
+
+### `TracingChannel.traceSync(fn[, context, thisArg, ...args])`
+
+Publishes start/end/error events around a sync function.
+
+## Complete Examples
+
+### Example 1: Subscribe and Publish
+
+```js
+const dc = require('bare-diagnostics-channel')
+
+const ch = dc.channel('db:query')
+ch.subscribe((data) => console.log('query', data))
+ch.publish({ sql: 'select 1' })
+```
+
+### Example 2: Named Helpers
+
+```js
+const dc = require('bare-diagnostics-channel')
+
+dc.subscribe('app:start', (data) => console.log(data))
+dc.channel('app:start').publish({ time: Date.now() })
+```
+
+### Example 3: Tracing Channel
+
+```js
+const { tracingChannel } = require('bare-diagnostics-channel')
+
+const t = tracingChannel('work')
+t.subscribe({
+  start: (ctx) => console.log('start', ctx),
+  end: (ctx) => console.log('end', ctx),
+  error: (ctx) => console.log('err', ctx)
+})
+
+t.traceSync(() => 42, { name: 'job' })
+```
+
+### Example 4: hasSubscribers Guard
+
+```js
+const dc = require('bare-diagnostics-channel')
+
+if (dc.hasSubscribers('metrics')) {
+  dc.channel('metrics').publish({ value: 1 })
+}
+```
+
+## Best Practices
+
+- **Check `hasSubscribers`** before building expensive payloads.
+- **Keep payloads small** to minimize overhead.
+
+## Performance Notes
+
+- Publish is synchronous; heavy subscribers can slow emitters.
+
+## Security Considerations
+
+- Do not publish sensitive data on shared channels.
+
+## Error Handling
+
+- Subscriber errors are rethrown asynchronously via `setImmediate`.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Instrumentation | **Ecosystem Role**: Diagnostics | **Dependencies**: None

modules/bare-distributable.md

@@ -0,0 +1,98 @@
+# bare-distributable
+
+Template repository for creating custom, statically linked Bare distributables. Intended for advanced scenarios where you need a bespoke Bare binary.
+
+## Install
+
+```bash
+git clone https://github.com/holepunchto/bare-distributable
+```
+
+## Overview
+
+- Generates a custom Bare binary with bundled JS entrypoint.
+- Uses `cmake-bare-bundle` to embed JS as a C header.
+- Links Bare statically and exports symbols for addons.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  A[src/main.js] --> B[cmake-bare-bundle]
+  B --> C[src/main.bundle.h]
+  C --> D[src/main.c]
+  D --> E[custom bare executable]
+  E --> F[bare static library]
+```
+
+## Build Notes
+
+Key CMake steps from `CMakeLists.txt`:
+
+- `fetch_package("github:holepunchto/[email protected]")`
+- `add_bare_bundle(... ENTRY src/main.js OUT src/main.bundle.h BUILTINS src/builtins.json)`
+- `link_bare_modules(bare_distributable)`
+
+The produced binary is named `my-bare` via `OUTPUT_NAME`.
+
+## Examples
+
+### 1) Minimal entrypoint
+
+```js
+// src/main.js
+console.log('Hello Bare!')
+```
+
+### 2) Bundle additional builtins
+
+```json
+// src/builtins.json
+{
+  "fs": "bare-fs",
+  "path": "bare-path"
+}
+```
+
+### 3) Change output name
+
+```cmake
+set_target_properties(bare_distributable PROPERTIES OUTPUT_NAME my-custom-bare)
+```
+
+### 4) Add native dependencies
+
+```cmake
+fetch_package("github:holepunchto/liburl")
+target_link_libraries(bare_distributable PUBLIC url)
+```
+
+## Best Practices
+
+- Use this template only for custom static distributions; prefer `bare-build` for typical app packaging.
+- Pin the Bare version in `fetch_package` to ensure reproducible builds.
+- Keep `builtins.json` minimal to reduce binary size.
+
+## Performance Notes
+
+- Static linking increases binary size but improves startup by bundling dependencies.
+- Embedded JS avoids runtime disk lookup, reducing cold start latency.
+
+## Security Considerations
+
+- Treat bundled JS as trusted code; update process when dependencies change.
+- Verify third-party native libraries and keep them pinned.
+
+## Integration Notes
+
+- Built with `cmake-bare-bundle` and `cmake-fetch`.
+- Produces a distributable Bare binary suitable for bundling with app installers.
+
+## Error Handling
+
+- Build failures typically come from CMake or toolchain configuration.
+- If `bare` sources fail to fetch, check network and GitHub auth.
+
+## License
+
+Apache-2.0

modules/bare-expo.md

@@ -0,0 +1,101 @@
+# bare-expo
+
+Example Expo project that embeds Bare in a React Native app using `react-native-bare-kit`.
+
+## Install
+
+```bash
+npm install
+```
+
+## Overview
+
+- Demonstrates how to bundle Bare inside an Expo-managed app.
+- Uses `react-native-bare-kit` and `react-native-b4a` for native bindings.
+- Run on iOS or Android via Expo tooling.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  A[Expo app] --> B[react-native-bare-kit]
+  B --> C[Bare runtime]
+  A --> D[react-native-b4a]
+  C --> E[JS modules / addons]
+```
+
+## Usage
+
+### iOS
+
+```bash
+npm run ios
+```
+
+### Android
+
+```bash
+npm run android
+```
+
+### Development server
+
+```bash
+npm run start
+```
+
+## Examples
+
+### 1) Install and run on iOS
+
+```bash
+npm install
+npm run ios
+```
+
+### 2) Install and run on Android
+
+```bash
+npm install
+npm run android
+```
+
+### 3) Add a Bare module
+
+```bash
+npm i bare-fs
+```
+
+```js
+// use within your React Native code that bridges to Bare
+```
+
+## Best Practices
+
+- Keep Bare workloads off the UI thread to avoid frame drops.
+- Use Expo config plugins to keep native config in sync.
+- Pin Bare-related dependencies for repeatable builds.
+
+## Performance Notes
+
+- Hermes/JS engine perf varies by platform; test on-device.
+- Native addon loading can add startup cost; preload strategically.
+
+## Security Considerations
+
+- Treat embedded native code as part of the app’s trusted base.
+- Avoid shipping development-only Bare modules in production builds.
+
+## Integration Notes
+
+- Built on `react-native-bare-kit` and `react-native-b4a`.
+- Pairs with Bare modules like `bare-fs`, `bare-path`, and `bare-subprocess`.
+
+## Error Handling
+
+- Expo build failures typically originate from native module config.
+- Use platform logs (Xcode/ADB) for Bare runtime errors.
+
+## License
+
+Apache-2.0

modules/bare-file-logger.md

@@ -0,0 +1,113 @@
+# bare-file-logger - File-backed Logger
+
+## Overview
+
+bare-file-logger writes log entries to a file on disk. It supports log rotation based on file size and exposes `debug/info/warn/error/fatal` methods compatible with `bare-console` backends.
+
+### Key Features
+
+- **File output**: Append log entries with timestamps.
+- **Rotation support**: Rotate or truncate when max size is reached.
+- **Event emitter**: Emits `rotate` after successful rotation.
+
+### Use Cases
+
+- **Persistent logs**: Store logs for later analysis.
+- **CLI tools**: Capture logs from Bare apps.
+
+## Installation
+
+```bash
+npm install bare-file-logger
+```
+
+## Quick Start
+
+```js
+const FileLog = require('bare-file-logger')
+
+const log = new FileLog('app.log')
+log.info('Hello %s', 'world')
+```
+
+## API Reference
+
+### `new FileLog(path[, options])`
+
+Options:
+
+- `maxSize` (number): Size hint for rotation.
+- `rotate` (function): `(path) => newPath | falsy`.
+- `rotateInterval` (number): Check interval in ms.
+
+### Methods
+
+- `debug`, `info`, `warn`, `error`, `fatal`
+- `clear()`
+- `close()`
+
+### Events
+
+- `rotate(path, dest)` after rotation.
+
+## Complete Examples
+
+### Example 1: Basic Logging
+
+```js
+const FileLog = require('bare-file-logger')
+
+const log = new FileLog('app.log')
+log.error('Oops')
+```
+
+### Example 2: Rotation
+
+```js
+const FileLog = require('bare-file-logger')
+
+const log = new FileLog('app.log', {
+  maxSize: 1024 * 1024,
+  rotate: (path) => path + '.' + Date.now()
+})
+```
+
+### Example 3: Rotate Event
+
+```js
+const FileLog = require('bare-file-logger')
+
+const log = new FileLog('app.log', { maxSize: 1 })
+log.on('rotate', (path, dest) => console.log(path, dest))
+```
+
+### Example 4: Use with bare-console
+
+```js
+const Console = require('bare-console')
+const FileLog = require('bare-file-logger')
+
+const log = new FileLog('app.log')
+const console = new Console(log)
+console.log('file log')
+```
+
+## Best Practices
+
+- **Set maxSize** for long-running services.
+- **Close logs** on shutdown to flush file descriptors.
+
+## Performance Notes
+
+- Writes are synchronous; high-frequency logging may impact performance.
+
+## Security Considerations
+
+- Store logs in protected directories to avoid leaking sensitive data.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Logging | **Ecosystem Role**: Persistent Logs | **Dependencies**: bare-fs, bare-logger

modules/bare-form-data.md

@@ -0,0 +1,121 @@
+# bare-form-data - FormData, Blob, and File
+
+## Overview
+
+bare-form-data implements WHATWG `FormData`, `Blob`, and `File` for Bare. It supports multipart form encoding via `toBlob()` for `multipart/form-data` payloads.
+
+### Key Features
+
+- **FormData API**: `append`, `set`, `get`, `getAll`, `delete`, `has`.
+- **Blob/File**: Standard file-like objects with streams and metadata.
+- **Multipart encoding**: `toBlob(formData)` helper.
+
+### Use Cases
+
+- **HTTP requests**: Build multipart form bodies.
+- **File uploads**: Wrap buffers or streams in `File`.
+- **Browser-like APIs**: Use familiar web APIs in Bare.
+
+## Installation
+
+```bash
+npm install bare-form-data
+```
+
+## Quick Start
+
+```js
+const { FormData, File } = require('bare-form-data')
+
+const form = new FormData()
+form.append('title', 'Hello')
+form.append('file', new File(['data'], 'file.txt', { type: 'text/plain' }))
+```
+
+## API Reference
+
+### `class FormData`
+
+- `append(name, value[, filename])`
+- `set(name, value[, filename])`
+- `get(name)` / `getAll(name)`
+- `delete(name)` / `has(name)`
+- `[Symbol.iterator]()`
+
+### `class Blob`
+
+- `size`, `type`
+- `stream()`, `arrayBuffer()`, `bytes()`, `buffer()`, `text()`
+
+### `class File extends Blob`
+
+- `name`, `lastModified`
+
+### Helpers
+
+- `isFormData(value)`
+- `Blob.isBlob(value)`
+- `File.isFile(value)`
+- `toBlob(formData[, mimeType])`
+
+## Complete Examples
+
+### Example 1: Multipart Blob
+
+```js
+const { FormData, toBlob } = require('bare-form-data')
+
+const form = new FormData()
+form.append('name', 'alice')
+
+const blob = toBlob(form)
+console.log(blob.type)
+```
+
+### Example 2: File Upload
+
+```js
+const { FormData, File } = require('bare-form-data')
+
+const form = new FormData()
+form.append('file', new File(['hello'], 'hello.txt'))
+```
+
+### Example 3: Iterate Entries
+
+```js
+const { FormData } = require('bare-form-data')
+
+const form = new FormData()
+form.append('a', '1')
+for (const [k, v] of form) console.log(k, v)
+```
+
+### Example 4: Blob Text
+
+```js
+const { Blob } = require('bare-form-data')
+
+const blob = new Blob(['hi'])
+console.log(await blob.text())
+```
+
+## Best Practices
+
+- **Use `toBlob`** to generate a proper multipart body.
+- **Set file `type`** for correct content-type headers.
+
+## Performance Notes
+
+- Multipart assembly concatenates buffers; large files may consume memory.
+
+## Security Considerations
+
+- Validate filenames and content types from untrusted sources.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Web API | **Ecosystem Role**: Form Encoding | **Dependencies**: bare-stream/web

modules/bare-format.md

@@ -0,0 +1,90 @@
+# bare-format - String Formatting
+
+## Overview
+
+bare-format implements printf-style string formatting, similar to Node's `util.format`. It supports common format specifiers and uses `bare-inspect` for object rendering.
+
+### Key Features
+
+- **Printf-style**: `%s`, `%d`, `%i`, `%f`, `%o`, `%O`, `%j`, `%%`.
+- **Object inspection**: Uses `bare-inspect` for non-string values.
+- **Options**: `formatWithOptions` supports inspect options.
+
+### Use Cases
+
+- **Logging**: Format messages consistently.
+- **Debugging**: Render objects in human-readable form.
+
+## Installation
+
+```bash
+npm install bare-format
+```
+
+## Quick Start
+
+```js
+const format = require('bare-format')
+
+console.log(format('Hello %s', 'world'))
+```
+
+## API Reference
+
+### `format(...args)`
+
+Formats a string using printf-style placeholders.
+
+### `formatWithOptions(opts, ...args)`
+
+Formats with `bare-inspect` options such as `colors`, `depth`, etc.
+
+## Complete Examples
+
+### Example 1: Basic Formatting
+
+```js
+const format = require('bare-format')
+
+format('value=%d', 42)
+```
+
+### Example 2: Object Output
+
+```js
+const format = require('bare-format')
+
+format('obj=%O', { a: 1 })
+```
+
+### Example 3: JSON
+
+```js
+const format = require('bare-format')
+
+format('json=%j', { a: 1 })
+```
+
+### Example 4: Options
+
+```js
+const { formatWithOptions } = require('bare-format')
+
+formatWithOptions({ colors: true }, '%O', { ok: true })
+```
+
+## Best Practices
+
+- **Use `%O`** for deep object inspection.
+- **Avoid `%j`** for circular objects (JSON stringify will throw).
+
+## Performance Notes
+
+- Formatting large objects can be expensive; use shallow logging where possible.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Utility | **Ecosystem Role**: Formatting | **Dependencies**: bare-inspect

modules/bare-headers.md

@@ -0,0 +1,72 @@
+# bare-headers - Bare Development Headers
+
+## Overview
+
+bare-headers provides development headers for the Bare runtime. It is intended for building native addons and tooling that depend on Bare's C/C++ headers.
+
+### Key Features
+
+- **C/C++ headers**: Packaged header files for Bare.
+- **Build support**: Used by native build systems and tooling.
+
+### Use Cases
+
+- **Native addons**: Compile extensions against Bare headers.
+- **Toolchains**: Build Bare-dependent binaries.
+
+## Installation
+
+```bash
+npm install bare-headers
+```
+
+## Building Headers
+
+To generate `include/` before publishing:
+
+```bash
+gh workflow run generate
+gh run watch
+gh run download --name include --dir include
+```
+
+## Complete Examples
+
+### Example 1: Use in CMake
+
+```cmake
+include_directories(${CMAKE_CURRENT_LIST_DIR}/node_modules/bare-headers/include)
+```
+
+### Example 2: Use in bare-dev Builds
+
+```bash
+bare-dev configure
+bare-dev build
+```
+
+### Example 3: Validate Include Paths
+
+```bash
+ls node_modules/bare-headers/include
+```
+
+## Best Practices
+
+- **Pin versions** to match the Bare runtime version you target.
+- **Automate header updates** in CI for reproducible builds.
+
+## Performance Notes
+
+- Not a runtime module; build-time only.
+
+## Security Considerations
+
+- Ensure headers come from trusted sources to avoid supply-chain issues.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Build Artifact | **Ecosystem Role**: Native Headers | **Dependencies**: None

modules/bare-hrtime.md

@@ -0,0 +1,94 @@
+# bare-hrtime - High Resolution Timers
+
+## Overview
+
+bare-hrtime provides high-resolution time measurements for Bare. It returns `[seconds, nanoseconds]` arrays or nanoseconds as a `BigInt` via `hrtime.bigint()`.
+
+### Key Features
+
+- **High precision**: Nanosecond resolution via native binding.
+- **Node-like API**: Mirrors `process.hrtime` semantics.
+- **Diff mode**: Pass a previous time to compute elapsed duration.
+
+### Use Cases
+
+- **Benchmarking**: Measure small code paths.
+- **Timing**: Build custom timers or profilers.
+- **Logging**: Use for accurate durations.
+
+## Installation
+
+```bash
+npm install bare-hrtime
+```
+
+## Quick Start
+
+```js
+const hrtime = require('bare-hrtime')
+
+const start = hrtime()
+// ... work
+const diff = hrtime(start)
+```
+
+## API Reference
+
+### `hrtime([past]) -> [seconds, nanoseconds]`
+
+If `past` is provided, returns elapsed time since `past`.
+
+### `hrtime.bigint() -> BigInt`
+
+Returns time in nanoseconds.
+
+## Complete Examples
+
+### Example 1: Elapsed Time
+
+```js
+const hrtime = require('bare-hrtime')
+
+const start = hrtime()
+// work
+const [s, ns] = hrtime(start)
+console.log(s, ns)
+```
+
+### Example 2: BigInt Time
+
+```js
+const hrtime = require('bare-hrtime')
+
+const t = hrtime.bigint()
+console.log(t)
+```
+
+### Example 3: Convert to ms
+
+```js
+const hrtime = require('bare-hrtime')
+
+const [s, ns] = hrtime()
+const ms = s * 1e3 + ns / 1e6
+```
+
+## Best Practices
+
+- **Use bigint for high precision** without floating conversions.
+- **Store start times** for diff computations.
+
+## Performance Notes
+
+- Native call overhead is low; suitable for fine-grained timing.
+
+## Security Considerations
+
+- None.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Utility | **Ecosystem Role**: Timing | **Dependencies**: native binding

modules/bare-inspect.md

@@ -0,0 +1,101 @@
+# bare-inspect - Object Inspection
+
+## Overview
+
+bare-inspect renders JavaScript values as human-readable strings. It supports custom inspect symbols, colors, depth control, array truncation, and circular reference tracking.
+
+### Key Features
+
+- **Pretty printing**: Structured output with configurable depth.
+- **Circular refs**: Detects and labels circular structures.
+- **Color styles**: Optional ANSI styling via `bare-ansi-escapes`.
+- **Custom inspect**: Honors `Symbol.for('bare.inspect')`.
+
+### Use Cases
+
+- **Debugging**: Print complex objects in logs.
+- **CLI output**: Show user-friendly data structures.
+
+## Installation
+
+```bash
+npm install bare-inspect
+```
+
+## Quick Start
+
+```js
+const inspect = require('bare-inspect')
+
+console.log(inspect({ hello: 'world' }))
+```
+
+## API Reference
+
+### `inspect(value[, opts]) -> string`
+
+Options:
+
+- `colors` (boolean)
+- `depth` (number)
+- `breakLength` (number)
+- `maxArrayLength` (number)
+- `stylize` (function)
+
+### `inspect.styles`
+
+Map of style names to ANSI codes.
+
+## Complete Examples
+
+### Example 1: Basic Inspect
+
+```js
+const inspect = require('bare-inspect')
+
+console.log(inspect([1, 2, 3]))
+```
+
+### Example 2: Colors
+
+```js
+const inspect = require('bare-inspect')
+
+console.log(inspect({ ok: true }, { colors: true }))
+```
+
+### Example 3: Depth Control
+
+```js
+const inspect = require('bare-inspect')
+
+console.log(inspect({ a: { b: { c: 1 } } }, { depth: 1 }))
+```
+
+### Example 4: Custom Inspect
+
+```js
+const inspect = require('bare-inspect')
+
+const obj = {
+  [Symbol.for('bare.inspect')]() { return { label: 'custom' } }
+}
+
+console.log(inspect(obj))
+```
+
+## Best Practices
+
+- **Limit depth** for large or recursive objects.
+- **Disable colors** for non-TTY logs.
+
+## Performance Notes
+
+- Large structures can be expensive; use `maxArrayLength`.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Utility | **Ecosystem Role**: Debug Output | **Dependencies**: bare-ansi-escapes, bare-type

modules/bare-ipc.md

@@ -0,0 +1,104 @@
+# bare-ipc - Pipe-based IPC
+
+## Overview
+
+bare-ipc provides lightweight IPC streams built on `bare-pipe` and `bare-stream`. It creates paired IPC ports and exposes a duplex stream interface.
+
+### Key Features
+
+- **Paired ports**: `IPC.open()` returns connected endpoints.
+- **Duplex streams**: `IPC` extends `Duplex`.
+- **Ref/unref**: Control event loop liveness.
+
+### Use Cases
+
+- **Process communication**: Connect parent/child processes.
+- **In-memory IPC**: Use pipe handles for fast messaging.
+
+## Installation
+
+```bash
+npm install bare-ipc
+```
+
+## Quick Start
+
+```js
+const IPC = require('bare-ipc')
+
+const [a, b] = IPC.open()
+const ipcA = new IPC(a)
+const ipcB = new IPC(b)
+
+ipcA.write('hello')
+ipcB.on('data', console.log)
+```
+
+## API Reference
+
+### `IPC.open() -> [IPCPort, IPCPort]`
+
+Creates a pair of connected ports.
+
+### `new IPC(port)`
+
+Creates a duplex IPC stream.
+
+### `ipc.ref()` / `ipc.unref()`
+
+Adjust reference counts to keep the loop alive or allow exit.
+
+### `class IPCPort`
+
+- `connect()`
+- `detached` (boolean)
+- `Symbol.for('bare.detach')` / `Symbol.for('bare.attach')`
+
+## Complete Examples
+
+### Example 1: Open Ports
+
+```js
+const IPC = require('bare-ipc')
+
+const [a, b] = IPC.open()
+```
+
+### Example 2: Duplex Stream
+
+```js
+const IPC = require('bare-ipc')
+
+const [a, b] = IPC.open()
+const client = a.connect()
+const server = b.connect()
+server.on('data', (d) => console.log(d.toString()))
+client.write('ping')
+```
+
+### Example 3: Ref/Unref
+
+```js
+const IPC = require('bare-ipc')
+
+const [a] = IPC.open()
+const ipc = a.connect()
+ipc.ref()
+ipc.unref()
+```
+
+## Best Practices
+
+- **Use ref/unref** during suspend/resume cycles.
+- **Handle backpressure** in large message streams.
+
+## Performance Notes
+
+- Pipes are efficient; throughput depends on chunk sizes.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: IPC | **Ecosystem Role**: Messaging | **Dependencies**: bare-pipe, bare-stream

modules/bare-jpeg.md

@@ -0,0 +1,78 @@
+# bare-jpeg - JPEG Encoder/Decoder
+
+## Overview
+
+bare-jpeg provides native JPEG decoding and encoding for Bare. It converts JPEG buffers into raw pixel data and encodes raw pixels to JPEG with adjustable quality.
+
+### Key Features
+
+- **Decode**: JPEG buffer -> `{ width, height, data }`.
+- **Encode**: Raw pixel data -> JPEG buffer with quality control.
+
+### Use Cases
+
+- **Image pipelines**: Resize or transform JPEGs.
+- **Asset processing**: Convert images for transport.
+
+## Installation
+
+```bash
+npm install bare-jpeg
+```
+
+## Quick Start
+
+```js
+const jpeg = require('bare-jpeg')
+
+const decoded = jpeg.decode(buffer)
+```
+
+## API Reference
+
+### `decode(buffer) -> { width, height, data }`
+
+### `encode({ data, width, height }[, options]) -> Buffer`
+
+Options:
+
+- `quality` (0-100, default 90)
+
+## Complete Examples
+
+### Example 1: Decode
+
+```js
+const jpeg = require('bare-jpeg')
+
+const decoded = jpeg.decode(buffer)
+```
+
+### Example 2: Encode with Quality
+
+```js
+const jpeg = require('bare-jpeg')
+
+const out = jpeg.encode({ data, width: 100, height: 100 }, { quality: 80 })
+```
+
+### Example 3: Round Trip
+
+```js
+const jpeg = require('bare-jpeg')
+
+const decoded = jpeg.decode(buffer)
+const reencoded = jpeg.encode(decoded)
+```
+
+## Best Practices
+
+- **Clamp quality** between 0-100 (handled internally).
+- **Validate data length** before encoding.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Media | **Ecosystem Role**: Image Processing | **Dependencies**: native binding

modules/bare-link.md

@@ -0,0 +1,110 @@
+# bare-link - Native Addon Linker
+
+## Overview
+
+bare-link links native addons for Bare across target hosts. It traverses dependency trees, resolves addon packages, and produces platform-specific linking outputs. A CLI is included for build pipelines.
+
+### Key Features
+
+- **Multi-host**: Build for multiple target hosts.
+- **Addon-aware**: Only processes packages with `addon: true`.
+- **Platform-specific**: Apple, Android, Linux, Windows linking paths.
+- **CLI**: Command-line linker for automation.
+
+### Use Cases
+
+- **Mobile builds**: Link addons ahead of time for iOS/Android.
+- **Desktop builds**: Generate linked addons for Bare runtimes.
+
+## Installation
+
+```bash
+npm install bare-link
+```
+
+## Quick Start
+
+```js
+const link = require('bare-link')
+
+for await (const resource of link('/path/to/module', { hosts: ['darwin-arm64'] })) {
+  console.log(resource)
+}
+```
+
+## CLI
+
+```bash
+bare-link --host darwin-arm64 --host ios-arm64
+```
+
+## API Reference
+
+### `link([base][, options]) -> AsyncIterable`
+
+Options:
+
+- `hosts` (string[])
+- `out` (string)
+- `preset` (string)
+- `sign` (boolean)
+- Apple signing: `identity`, `keychain`
+- Windows signing: `subject`, `subjectName`, `thumbprint`
+
+## Complete Examples
+
+### Example 1: Single Host
+
+```js
+const link = require('bare-link')
+
+for await (const r of link('.', { hosts: ['linux-x64'] })) {
+  console.log(r)
+}
+```
+
+### Example 2: Multi-host
+
+```js
+const link = require('bare-link')
+
+for await (const r of link('.', { hosts: ['darwin-arm64', 'ios-arm64'] })) {
+  console.log(r)
+}
+```
+
+### Example 3: CLI Usage
+
+```bash
+bare-link --host win32-x64 --out dist
+```
+
+### Example 4: Presets
+
+```js
+const link = require('bare-link')
+
+for await (const r of link('.', { preset: 'ios' })) {
+  console.log(r)
+}
+```
+
+## Best Practices
+
+- **Specify hosts** explicitly to avoid platform mismatch.
+- **Use signing options** for release builds.
+
+## Performance Notes
+
+- Linking cost scales with addon count and host targets.
+
+## Security Considerations
+
+- Protect signing credentials and keychains.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Build Tool | **Ecosystem Role**: Addon Linking | **Dependencies**: platform-specific linkers

modules/bare-logger.md

@@ -0,0 +1,94 @@
+# bare-logger - Low-level Logger
+
+## Overview
+
+bare-logger provides a low-level logger with severity methods that write through native bindings. It supports configurable color output and a composite logger for multiple backends.
+
+### Key Features
+
+- **Core methods**: `debug`, `info`, `warn`, `error`, `fatal`.
+- **Formatting**: Uses `bare-format` under the hood.
+- **Composite logging**: `CompositeLog` fan-out.
+
+### Use Cases
+
+- **Runtime logging**: Structured console-style output.
+- **Backend for bare-console**: Provide a log sink.
+
+## Installation
+
+```bash
+npm install bare-logger
+```
+
+## Quick Start
+
+```js
+const Log = require('bare-logger')
+
+const log = new Log()
+log.info('Hello %s', 'world')
+```
+
+## API Reference
+
+### `new Log([opts])`
+
+Options:
+
+- `colors` (boolean): Enable ANSI colors (default based on TTY).
+
+### Methods
+
+- `debug`, `info`, `warn`, `error`, `fatal`
+- `clear()` (no-op)
+
+### `CompositeLog`
+
+Construct with an iterable of logs and fan out calls.
+
+## Complete Examples
+
+### Example 1: Basic Log
+
+```js
+const Log = require('bare-logger')
+
+const log = new Log({ colors: true })
+log.warn('be careful')
+```
+
+### Example 2: Composite
+
+```js
+const Log = require('bare-logger')
+const FileLog = require('bare-file-logger')
+
+const log = new Log.CompositeLog([new Log(), new FileLog('app.log')])
+log.error('oops')
+```
+
+### Example 3: Format
+
+```js
+const Log = require('bare-logger')
+
+const log = new Log()
+log.info('value=%d', 42)
+```
+
+## Best Practices
+
+- **Disable colors** when logging to files.
+- **Use composite** to mirror output to multiple sinks.
+
+## Performance Notes
+
+- Formatting and native logging are lightweight; IO cost depends on backend.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Logging | **Ecosystem Role**: Log Core | **Dependencies**: bare-format

modules/bare-make.md

@@ -0,0 +1,99 @@
+# bare-make - CMake Build Generator
+
+## Overview
+
+bare-make is an opinionated build system generator for Bare based on CMake. It standardizes builds with Ninja and Clang while keeping projects compatible with plain CMake workflows.
+
+### Key Features
+
+- **Consistent toolchain**: Ninja + Clang across platforms.
+- **Simple JS API**: `generate`, `build`, `install`, `test`.
+- **CLI support**: Mirrors CMake workflows.
+
+### Use Cases
+
+- **Native addon builds**: Generate and build C/C++ projects.
+- **CI pipelines**: Reliable, repeatable builds.
+
+## Installation
+
+```bash
+npm install bare-make
+```
+
+## Quick Start
+
+```js
+const make = require('bare-make')
+
+await make.generate()
+await make.build()
+await make.install()
+```
+
+## API Reference
+
+### `generate([options])`
+### `build([options])`
+### `install([options])`
+### `test([options])`
+
+Options include `platform`, `arch`, `preset`, `debug`, `sanitize`, `define`, and output paths. See README for full flags.
+
+## CLI
+
+```bash
+bare-make generate
+bare-make build
+bare-make install
+bare-make test
+```
+
+## Complete Examples
+
+### Example 1: Debug Build
+
+```js
+const make = require('bare-make')
+
+await make.generate({ debug: true })
+await make.build()
+```
+
+### Example 2: Install to Prefix
+
+```js
+const make = require('bare-make')
+
+await make.install({ prefix: 'prebuilds' })
+```
+
+### Example 3: CLI with Target
+
+```bash
+bare-make build --target mylib
+```
+
+### Example 4: Run Tests
+
+```js
+const make = require('bare-make')
+
+await make.test({ timeout: 60 })
+```
+
+## Best Practices
+
+- **Use presets** for consistent build configurations.
+- **Cache builds** in CI to reduce build time.
+
+## Performance Notes
+
+- Build time depends on project size and platform toolchain.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Build Tool | **Ecosystem Role**: CMake Generator | **Dependencies**: CMake toolchain

modules/bare-module-lexer.md

@@ -0,0 +1,107 @@
+# bare-module-lexer - Heuristic Module Lexer
+
+## Overview
+
+bare-module-lexer is a fast heuristic lexer that detects import/export patterns in JavaScript modules. It is optimized for performance and supports common `require`, `import`, `import()` and Bare-specific addon/asset patterns.
+
+### Key Features
+
+- **Fast scanning**: Heuristic lexer for common patterns.
+- **Import/export detection**: Handles CJS and ESM forms.
+- **Bare-specific types**: `require.addon`, `require.asset`, `import.meta.*`.
+
+### Use Cases
+
+- **Bundling**: Build dependency graphs quickly.
+- **Static analysis**: Locate imports/exports in source.
+
+## Installation
+
+```bash
+npm install bare-module-lexer
+```
+
+## Quick Start
+
+```js
+const lex = require('bare-module-lexer')
+
+const { imports, exports } = lex('const x = require("./x")')
+```
+
+## API Reference
+
+### `lex(source[, encoding][, options]) -> { imports, exports }`
+
+- `imports`: Array of import records.
+- `exports`: Array of export records.
+
+### Import Record
+
+- `specifier` (string)
+- `type` (number bitmask)
+- `names` (string[])
+- `position` ([importStart, specifierStart, specifierEnd])
+
+### Export Record
+
+- `name` (string)
+- `position` ([exportStart, nameStart, nameEnd])
+
+### `lex.constants`
+
+Bitmask constants:
+
+- `REQUIRE`, `IMPORT`, `DYNAMIC`, `ADDON`, `ASSET`, `RESOLVE`, `REEXPORT`
+
+## Complete Examples
+
+### Example 1: Require
+
+```js
+const lex = require('bare-module-lexer')
+
+const res = lex("const x = require('./x')")
+console.log(res.imports)
+```
+
+### Example 2: ESM Import
+
+```js
+const lex = require('bare-module-lexer')
+
+const res = lex("import x from './x.js'")
+```
+
+### Example 3: Addon Import
+
+```js
+const lex = require('bare-module-lexer')
+
+const res = lex('const addon = require.addon()')
+```
+
+### Example 4: Export Detection
+
+```js
+const lex = require('bare-module-lexer')
+
+const res = lex('exports.foo = 1')
+console.log(res.exports)
+```
+
+## Best Practices
+
+- **Treat results as heuristic**; it is not a full parser.
+- **Use with resolver** to validate actual file existence.
+
+## Performance Notes
+
+- Designed for speed; suitable for large codebases.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Tooling | **Ecosystem Role**: Lexer | **Dependencies**: native binding

modules/bare-module-resolve.md

@@ -0,0 +1,117 @@
+# bare-module-resolve - Module Resolution Engine
+
+## Overview
+
+bare-module-resolve implements a low-level module resolution algorithm for Bare. It is generator-based and yields package manifests and resolution candidates, allowing callers to control filesystem or URL checks.
+
+### Key Features
+
+- **Generator-driven**: Yields package.json reads and resolution candidates.
+- **Sync and async**: Supports synchronous and asynchronous iteration.
+- **Import maps**: Supports `imports` and `exports` resolution.
+- **Builtin/deferred**: Special protocols for builtins and deferred specifiers.
+
+### Use Cases
+
+- **Bundlers**: Resolve module graphs for packaging.
+- **Custom loaders**: Implement resolution against virtual filesystems.
+
+## Installation
+
+```bash
+npm install bare-module-resolve
+```
+
+## Quick Start
+
+```js
+const resolve = require('bare-module-resolve')
+
+function readPackage(url) { return null }
+
+for (const r of resolve('./file.js', new URL('file:///dir/'), readPackage)) {
+  console.log(r)
+}
+```
+
+## API Reference
+
+### `resolve(specifier, parentURL[, options][, readPackage])`
+
+Returns an iterable/async-iterable of resolution candidates.
+
+### Options
+
+- `imports`, `builtins`, `builtinProtocol`
+- `defer`, `deferredProtocol`
+- `conditions`, `matchedConditions`, `matchedTargets`
+- `engines`, `extensions`, `resolutions`
+
+### Constants
+
+- `UNRESOLVED`, `YIELDED`, `RESOLVED`, `CYCLIC`
+
+## Complete Examples
+
+### Example 1: Async Resolution
+
+```js
+const resolve = require('bare-module-resolve')
+
+for await (const r of resolve('./x.js', new URL('file:///dir/'), async () => null)) {
+  console.log(r)
+}
+```
+
+### Example 2: Builtins
+
+```js
+const resolve = require('bare-module-resolve')
+
+const opts = { builtins: ['fs'], builtinProtocol: 'builtin:' }
+for (const r of resolve('fs', new URL('file:///dir/'), opts)) {
+  console.log(r)
+}
+```
+
+### Example 3: Extensions
+
+```js
+const resolve = require('bare-module-resolve')
+
+const opts = { extensions: ['.js', '.json'] }
+for (const r of resolve('./foo', new URL('file:///dir/'), opts)) {
+  console.log(r)
+}
+```
+
+### Example 4: Import Maps
+
+```js
+const resolve = require('bare-module-resolve')
+
+const opts = { imports: { '#x': './x.js' } }
+for (const r of resolve('#x', new URL('file:///dir/'), opts)) {
+  console.log(r)
+}
+```
+
+## Best Practices
+
+- **Provide readPackage** for accurate package resolution.
+- **Use async iteration** if package reads are async.
+
+## Performance Notes
+
+- Generator design allows streaming resolution without loading entire graph.
+
+## Security Considerations
+
+- Validate input specifiers to avoid path traversal issues.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Tooling | **Ecosystem Role**: Resolver | **Dependencies**: bare-semver

modules/bare-module-traverse.md

@@ -0,0 +1,112 @@
+# bare-module-traverse - Module Graph Traversal
+
+## Overview
+
+bare-module-traverse walks a module graph in Bare. It yields dependencies discovered via `bare-module-lexer` and `bare-module-resolve`, allowing callers to supply custom module readers and prefix listers.
+
+### Key Features
+
+- **Generator-based traversal**: Sync and async iteration.
+- **Addon/asset discovery**: Tracks `addons` and `assets` arrays.
+- **Custom resolution**: Pluggable resolver functions.
+
+### Use Cases
+
+- **Bundlers**: Build a full dependency graph.
+- **Static analysis**: Find and process all dependencies.
+
+## Installation
+
+```bash
+npm install bare-module-traverse
+```
+
+## Quick Start
+
+```js
+const traverse = require('bare-module-traverse')
+
+for (const dep of traverse(new URL('file:///app/index.js'), () => null)) {
+  console.log(dep)
+}
+```
+
+## API Reference
+
+### `traverse(url[, options], readModule[, listPrefix])`
+
+- `readModule(url)` returns source or `null`.
+- `listPrefix(url)` yields URLs for matching prefixes.
+
+### `traverse.constants`
+
+File type constants: `SCRIPT`, `MODULE`, `JSON`, `BUNDLE`, `ADDON`, `BINARY`, `TEXT`, `ASSET`.
+
+### `traverse.resolve`
+
+Resolver helpers: `module`, `addon`, `default`, `bare`, `node`.
+
+## Complete Examples
+
+### Example 1: Sync Traversal
+
+```js
+const traverse = require('bare-module-traverse')
+
+function read(url) { return null }
+for (const dep of traverse(new URL('file:///app/index.js'), read)) {
+  console.log(dep.url.href)
+}
+```
+
+### Example 2: Async Traversal
+
+```js
+const traverse = require('bare-module-traverse')
+
+async function read(url) { return null }
+for await (const dep of traverse(new URL('file:///app/index.js'), read)) {
+  console.log(dep.url.href)
+}
+```
+
+### Example 3: Custom Resolver
+
+```js
+const traverse = require('bare-module-traverse')
+
+const opts = { resolve: traverse.resolve.node }
+for (const dep of traverse(new URL('file:///app/index.js'), opts, () => null)) {
+  console.log(dep.url.href)
+}
+```
+
+### Example 4: Asset Prefix Listing
+
+```js
+const traverse = require('bare-module-traverse')
+
+function* listPrefix(url) {
+  // yield matching URLs
+}
+
+for (const dep of traverse(new URL('file:///app/index.js'), () => null, listPrefix)) {
+  console.log(dep.url.href)
+}
+```
+
+## Best Practices
+
+- **Provide listPrefix** when you use asset imports.
+- **Use async iteration** if module IO is async.
+
+## Performance Notes
+
+- Traversal cost scales with graph size and IO.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Tooling | **Ecosystem Role**: Dependency Traversal | **Dependencies**: bare-module-lexer, bare-module-resolve

modules/bare-open.md

@@ -0,0 +1,81 @@
+# bare-open - Cross-platform App Launcher
+
+## Overview
+
+bare-open launches an application or file using platform-native mechanisms. It is a small wrapper over a native binding.
+
+### Key Features
+
+- **Cross-platform**: Works on macOS, Linux, and Windows.
+- **Simple API**: `open(app[, argument])`.
+
+### Use Cases
+
+- **Open URLs**: Launch a browser or app.
+- **Open files**: Delegate to OS defaults.
+
+## Installation
+
+```bash
+npm install bare-open
+```
+
+## Quick Start
+
+```js
+const open = require('bare-open')
+
+open('/Applications/Firefox.app')
+```
+
+## API Reference
+
+### `open(app[, argument])`
+
+Launch the given application or file. If `argument` is provided, it is passed as an additional argument to the launcher.
+
+## Complete Examples
+
+### Example 1: Open App
+
+```js
+const open = require('bare-open')
+
+open('/Applications/Firefox.app')
+```
+
+### Example 2: Open URL
+
+```js
+const open = require('bare-open')
+
+open('https://pears.com')
+```
+
+### Example 3: Open File with Argument
+
+```js
+const open = require('bare-open')
+
+open('/Applications/Preview.app', '/path/to/file.pdf')
+```
+
+## Best Practices
+
+- **Validate inputs** to avoid launching unintended targets.
+- **Handle platform differences** in app paths.
+
+## Performance Notes
+
+- Launch time depends on OS and target application.
+
+## Security Considerations
+
+- Avoid passing untrusted paths or URLs.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Utility | **Ecosystem Role**: App Launching | **Dependencies**: native binding

modules/bare-pack-drive.md

@@ -0,0 +1,83 @@
+# bare-pack-drive - Bundle Drives
+
+## Overview
+
+bare-pack-drive packs a drive (e.g., Hyperdrive) into a Bare bundle. It adapts `bare-pack` to a drive API by implementing `readModule` and `listPrefix` against drive methods.
+
+### Key Features
+
+- **Drive support**: Uses `drive.get` and `drive.list`.
+- **Bare bundle output**: Returns a `bare-bundle` instance.
+
+### Use Cases
+
+- **Hyperdrive packaging**: Bundle drive content for distribution.
+- **Offline deployment**: Generate bundles from drive-based apps.
+
+## Installation
+
+```bash
+npm install bare-pack-drive
+```
+
+## Quick Start
+
+```js
+const pack = require('bare-pack-drive')
+
+const bundle = await pack(drive, '/entry.js')
+```
+
+## API Reference
+
+### `pack(drive[, entry][, options]) -> Promise<Bundle>`
+
+- `drive`: Drive with `get()` and `list()`.
+- `entry`: Entry path (default `/index.js`).
+- `options`: Forwarded to `bare-pack`.
+
+## Complete Examples
+
+### Example 1: Hyperdrive Bundle
+
+```js
+const pack = require('bare-pack-drive')
+const Hyperdrive = require('hyperdrive')
+
+const drive = new Hyperdrive('./app')
+await drive.ready()
+
+const bundle = await pack(drive, '/boot.js')
+```
+
+### Example 2: Default Entry
+
+```js
+const pack = require('bare-pack-drive')
+
+const bundle = await pack(drive)
+```
+
+### Example 3: Options
+
+```js
+const pack = require('bare-pack-drive')
+
+const bundle = await pack(drive, '/index.js', { concurrency: 8 })
+```
+
+## Best Practices
+
+- **Ensure drive readiness** before packing.
+- **Use proper entry paths** to avoid missing modules.
+
+## Performance Notes
+
+- Drive list operations can dominate runtime for large drives.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Tooling | **Ecosystem Role**: Drive Bundling | **Dependencies**: bare-pack

modules/bare-pack.md

@@ -0,0 +1,89 @@
+# bare-pack - Bundle Packing
+
+## Overview
+
+bare-pack bundles a module graph into a `bare-bundle` archive. It traverses dependencies, resolves imports, and records addon and asset references. It is storage-agnostic, relying on callbacks for reading modules and listing prefixes.
+
+### Key Features
+
+- **Graph traversal**: Uses `bare-module-traverse`.
+- **Addon/asset capture**: Records addon and asset entries.
+- **CLI**: Build bundles from the command line.
+
+### Use Cases
+
+- **Packaging**: Generate `.bundle` artifacts for Bare runtimes.
+- **Tooling**: Build bundles for deployment or distribution.
+
+## Installation
+
+```bash
+npm install bare-pack
+```
+
+## Quick Start
+
+```js
+const pack = require('bare-pack')
+
+const bundle = await pack(new URL('file:///app/index.js'), readModule, listPrefix)
+```
+
+## API Reference
+
+### `pack(url[, options], readModule[, listPrefix]) -> Promise<Bundle>`
+
+Options:
+
+- `concurrency` (number)
+- Options from `bare-module-traverse`
+
+### CLI
+
+```bash
+bare-pack --out app.bundle index.js
+```
+
+## Complete Examples
+
+### Example 1: Build Bundle
+
+```js
+const pack = require('bare-pack')
+
+const bundle = await pack(new URL('file:///app/index.js'), read, list)
+```
+
+### Example 2: CLI with Host
+
+```bash
+bare-pack --host darwin-arm64 index.js
+```
+
+### Example 3: Linked Addons
+
+```bash
+bare-pack --linked index.js
+```
+
+### Example 4: Builtins List
+
+```bash
+bare-pack --builtins builtins.json index.js
+```
+
+## Best Practices
+
+- **Provide listPrefix** for asset patterns.
+- **Use `--linked`** for mobile targets where addons must be linked.
+
+## Performance Notes
+
+- Bundle construction cost scales with graph size.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Tooling | **Ecosystem Role**: Bundling | **Dependencies**: bare-module-traverse, bare-bundle

modules/bare-performance.md

@@ -0,0 +1,135 @@
+# bare-performance - Performance Hooks for Bare
+
+## Overview
+
+bare-performance provides performance metrics compatible with Node's `perf_hooks`. It exposes `performance.now()`, event loop utilization, timing entries, and histograms for event loop delay.
+
+### Key Features
+
+- **`performance.now()`**: High-resolution timing.
+- **Event loop utilization**: `eventLoopUtilization()` and idle time.
+- **Performance entries**: Marks/measures and observers.
+- **Histograms**: `createHistogram` and `monitorEventLoopDelay`.
+
+### Use Cases
+
+- **Profiling**: Measure event loop delay and CPU utilization.
+- **Benchmarking**: High-resolution timing for code paths.
+- **Observability**: Collect metrics for logs or dashboards.
+
+## Installation
+
+```bash
+npm install bare-performance
+```
+
+## Quick Start
+
+```js
+const performance = require('bare-performance')
+
+const start = performance.now()
+// work
+console.log(performance.now() - start)
+```
+
+## API Reference
+
+### Timing
+
+- `performance.now()`
+- `performance.timeOrigin`
+
+### Event Loop
+
+- `performance.eventLoopUtilization([prev, current])`
+- `performance.idleTime()`
+- `performance.metricsInfo()`
+
+### Entries and Observers
+
+- `PerformanceEntry`, `PerformanceMark`, `PerformanceMeasure`
+- `PerformanceObserver`, `PerformanceObserverEntryList`
+- `mark(name)`, `measure(name, start, end)`
+- `clearMarks([name])`, `clearMeasures([name])`
+- `getEntries()`, `getEntriesByName(name)`, `getEntriesByType(type)`
+
+### Histograms
+
+- `createHistogram(opts)`
+- `monitorEventLoopDelay(opts)`
+
+### Node compatibility
+
+- `performance.performance` (self)
+- `performance.nodeTiming` with `idleTime`/`uvMetricsInfo`
+
+## Complete Examples
+
+### Example 1: now() Timing
+
+```js
+const perf = require('bare-performance')
+
+const t0 = perf.now()
+// work
+const t1 = perf.now()
+console.log(t1 - t0)
+```
+
+### Example 2: Event Loop Utilization
+
+```js
+const perf = require('bare-performance')
+
+const u1 = perf.eventLoopUtilization()
+setTimeout(() => {
+  const u2 = perf.eventLoopUtilization(u1)
+  console.log(u2.utilization)
+}, 1000)
+```
+
+### Example 3: Marks and Measures
+
+```js
+const perf = require('bare-performance')
+
+perf.mark('start')
+// work
+perf.mark('end')
+perf.measure('work', 'start', 'end')
+console.log(perf.getEntriesByName('work'))
+```
+
+### Example 4: Event Loop Delay Histogram
+
+```js
+const perf = require('bare-performance')
+
+const h = perf.monitorEventLoopDelay()
+h.enable()
+setTimeout(() => {
+  console.log(h.mean)
+  h.disable()
+}, 1000)
+```
+
+## Best Practices
+
+- **Reset marks** to avoid memory growth.
+- **Use histograms** for long-term monitoring.
+
+## Performance Notes
+
+- Observer and histogram overhead are modest but non-zero.
+
+## Security Considerations
+
+- Avoid exposing fine-grained timing data to untrusted code in high-risk contexts.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Observability | **Ecosystem Role**: Performance Metrics | **Dependencies**: native binding

modules/bare-png.md

@@ -0,0 +1,75 @@
+# bare-png - PNG Encoder/Decoder
+
+## Overview
+
+bare-png provides native PNG decoding and encoding for Bare. It converts PNG buffers to raw pixel data and back.
+
+### Key Features
+
+- **Decode**: PNG buffer -> `{ width, height, data }`.
+- **Encode**: Raw pixel data -> PNG buffer.
+
+### Use Cases
+
+- **Image processing**: Load and modify PNGs.
+- **Asset pipelines**: Convert images to raw data.
+
+## Installation
+
+```bash
+npm install bare-png
+```
+
+## Quick Start
+
+```js
+const png = require('bare-png')
+
+const decoded = png.decode(imageBuffer)
+```
+
+## API Reference
+
+### `decode(buffer) -> { width, height, data }`
+
+### `encode({ data, width, height }) -> Buffer`
+
+## Complete Examples
+
+### Example 1: Decode
+
+```js
+const png = require('bare-png')
+
+const decoded = png.decode(buffer)
+console.log(decoded.width, decoded.height)
+```
+
+### Example 2: Encode
+
+```js
+const png = require('bare-png')
+
+const out = png.encode({ data, width: 100, height: 100 })
+```
+
+### Example 3: Round Trip
+
+```js
+const png = require('bare-png')
+
+const decoded = png.decode(buffer)
+const reencoded = png.encode(decoded)
+```
+
+## Best Practices
+
+- **Validate buffer** before decoding.
+- **Ensure data length** matches width/height.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Media | **Ecosystem Role**: Image Processing | **Dependencies**: native binding

modules/bare-prebuild.md

@@ -0,0 +1,84 @@
+# bare-prebuild - Recursive Addon Prebuilder
+
+## Overview
+
+bare-prebuild recursively prebuilds native addons from source. It walks a module tree, detects `addon` packages, and runs Bare build steps to install prebuilds under each module's `prebuilds/` directory.
+
+### Key Features
+
+- **Recursive**: Walks `node_modules` to prebuild all addons.
+- **Bare toolchain**: Uses `bare-make` for generate/build/install.
+- **CLI**: Run from terminal with platform/arch options.
+
+### Use Cases
+
+- **Release preparation**: Generate prebuilds for distribution.
+- **CI pipelines**: Prebuild native modules ahead of packaging.
+
+## Installation
+
+```bash
+npm install bare-prebuild
+```
+
+## Quick Start
+
+```js
+const prebuild = require('bare-prebuild')
+
+await prebuild('/path/to/module')
+```
+
+## API Reference
+
+### `prebuild([base][, options]) -> Promise<void>`
+
+Options:
+
+- `platform`, `arch`, `simulator`, `environment`
+- `sanitize`, `debug`, `define`
+- `verbose`, `stdio`
+
+## CLI
+
+```bash
+bare-prebuild --platform linux --arch x64
+```
+
+## Complete Examples
+
+### Example 1: Default Prebuild
+
+```js
+const prebuild = require('bare-prebuild')
+
+await prebuild('.')
+```
+
+### Example 2: CLI with Debug
+
+```bash
+bare-prebuild --debug
+```
+
+### Example 3: Cross Target
+
+```bash
+bare-prebuild --platform darwin --arch arm64
+```
+
+## Best Practices
+
+- **Run in clean workspaces** to avoid stale artifacts.
+- **Ensure build tools installed** (`bare-make`, compilers).
+
+## Performance Notes
+
+- Prebuilding is CPU/IO intensive; expect longer CI times.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Build Tool | **Ecosystem Role**: Prebuild Automation | **Dependencies**: bare-make

modules/bare-punycode.md

@@ -0,0 +1,82 @@
+# bare-punycode - Punycode Utilities
+
+## Overview
+
+bare-punycode exposes the `punycode` module for Bare. It is a direct re-export of the standard `punycode` implementation for encoding/decoding internationalized domain names.
+
+### Key Features
+
+- **Direct re-export**: Same API as `punycode`.
+- **IDN support**: Convert between Unicode and ASCII (Punycode).
+
+### Use Cases
+
+- **Domain handling**: IDN normalization for URLs.
+- **Legacy compatibility**: Support for older URL parsing flows.
+
+## Installation
+
+```bash
+npm install bare-punycode
+```
+
+## Quick Start
+
+```js
+const punycode = require('bare-punycode')
+
+console.log(punycode.toASCII('mañana.com'))
+```
+
+## API Reference
+
+This module re-exports `punycode` APIs, including:
+
+- `toASCII(domain)`
+- `toUnicode(domain)`
+- `encode(string)`
+- `decode(string)`
+- `ucs2` helpers
+
+## Complete Examples
+
+### Example 1: Domain to ASCII
+
+```js
+const punycode = require('bare-punycode')
+
+console.log(punycode.toASCII('пример.рф'))
+```
+
+### Example 2: Domain to Unicode
+
+```js
+const punycode = require('bare-punycode')
+
+console.log(punycode.toUnicode('xn--e1afmkfd.xn--p1ai'))
+```
+
+### Example 3: Encode/Decode
+
+```js
+const punycode = require('bare-punycode')
+
+const encoded = punycode.encode('mañana')
+const decoded = punycode.decode(encoded)
+```
+
+## Best Practices
+
+- **Prefer URL APIs** for modern parsing where available.
+- **Normalize input** before applying punycode.
+
+## Performance Notes
+
+- Punycode operations are CPU-bound but fast for typical domains.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Utility | **Ecosystem Role**: IDN Support | **Dependencies**: punycode

modules/bare-querystring.md

@@ -0,0 +1,95 @@
+# bare-querystring - Query String Utilities
+
+## Overview
+
+bare-querystring provides URL query string parsing and formatting for Bare. It includes `parse`/`stringify` and alias helpers `decode`/`encode`.
+
+### Key Features
+
+- **Parse strings** into objects.
+- **Stringify objects** into query strings.
+- **Custom separators** and key/value delimiters.
+
+### Use Cases
+
+- **URL parsing**: Decode query strings in CLI or runtime.
+- **Request building**: Generate query strings for HTTP requests.
+
+## Installation
+
+```bash
+npm install bare-querystring
+```
+
+## Quick Start
+
+```js
+const qs = require('bare-querystring')
+
+qs.decode('name=ferret')
+```
+
+## API Reference
+
+### `parse(str[, sep='&'][, eq='='])`
+
+Parse a query string into an object.
+
+### `stringify(obj[, sep='&'][, eq='='])`
+
+Serialize an object into a query string.
+
+### Aliases
+
+- `decode` → `parse`
+- `encode` → `stringify`
+
+## Complete Examples
+
+### Example 1: Parse
+
+```js
+const qs = require('bare-querystring')
+
+const obj = qs.parse('a=1&b=2')
+```
+
+### Example 2: Stringify
+
+```js
+const qs = require('bare-querystring')
+
+const str = qs.stringify({ a: 1, b: 2 })
+```
+
+### Example 3: Custom Delimiters
+
+```js
+const qs = require('bare-querystring')
+
+const obj = qs.parse('a:1;b:2', ';', ':')
+```
+
+### Example 4: Arrays
+
+```js
+const qs = require('bare-querystring')
+
+const str = qs.stringify({ a: [1, 2] })
+```
+
+## Best Practices
+
+- **Use URLSearchParams** for modern URL handling if available.
+- **Encode values** to avoid injection in query strings.
+
+## Performance Notes
+
+- Simple string operations; suitable for small to medium payloads.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Utility | **Ecosystem Role**: URL Encoding | **Dependencies**: None

modules/bare-queue-microtask.md

@@ -0,0 +1,79 @@
+# bare-queue-microtask - Microtask Queue
+
+## Overview
+
+bare-queue-microtask provides a `queueMicrotask` implementation for Bare. It schedules callbacks on the microtask queue using a resolved Promise and surfaces errors as uncaught exceptions.
+
+### Key Features
+
+- **Microtask scheduling**: Runs before the next macrotask.
+- **Error reporting**: Exceptions are thrown asynchronously (not as Promise rejections).
+
+### Use Cases
+
+- **Deferring work**: Schedule quick follow-up operations.
+- **Ordering**: Ensure callbacks run after current call stack.
+
+## Installation
+
+```bash
+npm install bare-queue-microtask
+```
+
+## Quick Start
+
+```js
+const queueMicrotask = require('bare-queue-microtask')
+
+queueMicrotask(() => console.log('microtask'))
+```
+
+## API Reference
+
+### `queueMicrotask(fn)`
+
+Schedule `fn` to run in the microtask queue.
+
+## Complete Examples
+
+### Example 1: Basic Usage
+
+```js
+const queueMicrotask = require('bare-queue-microtask')
+
+queueMicrotask(() => console.log('after stack'))
+```
+
+### Example 2: Ordering
+
+```js
+const queueMicrotask = require('bare-queue-microtask')
+
+console.log('start')
+queueMicrotask(() => console.log('micro'))
+console.log('end')
+```
+
+### Example 3: Error Handling
+
+```js
+const queueMicrotask = require('bare-queue-microtask')
+
+queueMicrotask(() => { throw new Error('boom') })
+```
+
+## Best Practices
+
+- **Keep microtasks short** to avoid starving IO.
+- **Handle errors** to avoid crashing the process.
+
+## Performance Notes
+
+- Uses Promise microtasks; very low overhead.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Runtime Utility | **Ecosystem Role**: Scheduling | **Dependencies**: None

modules/bare-readline.md

@@ -0,0 +1,116 @@
+# bare-readline - Interactive Line Editor
+
+## Overview
+
+bare-readline provides interactive line editing with history, cursor movement, and terminal resize handling for Bare. It exposes a `createInterface` API similar to Node's `readline`.
+
+### Key Features
+
+- **Line editing**: Cursor movement, insertion, and deletion.
+- **History**: Up/down navigation with stored entries.
+- **TTY-aware**: Resizes and redraws prompt correctly.
+- **Stream-based**: Readable interface emitting `line` events.
+
+### Use Cases
+
+- **Interactive CLIs**: Prompt-based applications.
+- **REPLs**: Build custom REPL-like interfaces.
+
+## Installation
+
+```bash
+npm install bare-readline
+```
+
+## Quick Start
+
+```js
+const readline = require('bare-readline')
+
+const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+rl.on('data', (line) => {
+  console.log(line)
+  rl.prompt()
+}).prompt()
+```
+
+## API Reference
+
+### `createInterface(opts) -> Readline`
+
+Options:
+
+- `input`: Readable stream
+- `output`: Writable stream
+- `prompt`: Prompt string (default `> `)
+- `crlfDelay`: CRLF delay threshold
+
+### Readline Instance
+
+- `prompt()`
+- `setPrompt(str)` / `getPrompt()`
+- `close()`
+- `clearLine()`
+- `line` (current line)
+- `cursor` (cursor index)
+
+Events:
+
+- `data` / `line`
+- `history` (history array)
+
+## Complete Examples
+
+### Example 1: Basic Prompt
+
+```js
+const readline = require('bare-readline')
+
+const rl = readline.createInterface({ input, output })
+rl.on('line', (line) => console.log('> ', line))
+rl.prompt()
+```
+
+### Example 2: Custom Prompt
+
+```js
+const readline = require('bare-readline')
+
+const rl = readline.createInterface({ input, output })
+rl.setPrompt('cmd> ')
+rl.prompt()
+```
+
+### Example 3: History Handling
+
+```js
+const readline = require('bare-readline')
+
+const rl = readline.createInterface({ input, output })
+rl.on('history', (entries) => console.log(entries))
+```
+
+### Example 4: Close on Ctrl+C
+
+```js
+const readline = require('bare-readline')
+
+const rl = readline.createInterface({ input, output })
+rl.on('close', () => console.log('bye'))
+```
+
+## Best Practices
+
+- **Call `prompt()`** after handling a line.
+- **Handle `close()`** to clean up on exit.
+
+## Performance Notes
+
+- Redraw costs depend on terminal size and line length.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: CLI Utility | **Ecosystem Role**: Input Editing | **Dependencies**: bare-ansi-escapes

modules/bare-realm.md

@@ -0,0 +1,88 @@
+# bare-realm - JavaScript Realms
+
+## Overview
+
+bare-realm provides isolated JavaScript realms (separate global environments). It supports evaluation within a realm and is used by `bare-vm`.
+
+### Key Features
+
+- **Isolated globals**: Separate global scope from main runtime.
+- **Evaluation**: Execute code within the realm.
+
+### Use Cases
+
+- **Sandboxing**: Run untrusted code in a separate realm.
+- **VM contexts**: Build vm-like APIs.
+
+## Installation
+
+```bash
+npm install bare-realm
+```
+
+## Quick Start
+
+```js
+const Realm = require('bare-realm')
+
+const realm = new Realm()
+realm.evaluate('globalThis.foo = 42')
+```
+
+## API Reference
+
+### `new Realm()`
+
+Creates a new realm.
+
+### `realm.evaluate(code[, options])`
+
+Options:
+
+- `filename` (string)
+- `offset` (number)
+
+## Complete Examples
+
+### Example 1: Evaluate Code
+
+```js
+const Realm = require('bare-realm')
+
+const realm = new Realm()
+console.log(realm.evaluate('1 + 1'))
+```
+
+### Example 2: Separate Globals
+
+```js
+const Realm = require('bare-realm')
+
+const realm = new Realm()
+realm.evaluate('globalThis.x = 1')
+console.log(globalThis.x) // undefined
+```
+
+### Example 3: Filename Metadata
+
+```js
+const Realm = require('bare-realm')
+
+realm.evaluate('throw new Error("boom")', { filename: 'sandbox.js' })
+```
+
+## Best Practices
+
+- **Avoid sharing mutable state** across realms.
+- **Use filename** to improve stack traces.
+
+## Performance Notes
+
+- Creating realms has overhead; reuse when possible.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Runtime Utility | **Ecosystem Role**: Isolation | **Dependencies**: native binding

modules/bare-run.md

@@ -0,0 +1,89 @@
+# bare-run - Cross-platform Script Runner
+
+## Overview
+
+bare-run bundles a module graph and runs it across platforms (desktop, Android, iOS). It builds a Bare bundle, assigns a bundle ID, and launches the appropriate runtime/device workflow.
+
+### Key Features
+
+- **Multi-platform**: Desktop, Android, iOS.
+- **Bundling**: Uses `bare-pack` and `bare-bundle-id`.
+- **Device selection**: Target specific devices or simulators.
+- **CLI**: Run scripts from the terminal.
+
+### Use Cases
+
+- **Mobile testing**: Run bundled apps on devices.
+- **Cross-platform CI**: Validate app execution on multiple targets.
+
+## Installation
+
+```bash
+npm install bare-run
+```
+
+## Quick Start
+
+```js
+const run = require('bare-run')
+
+await run('./src/app.js', { host: 'android-arm64', device: 'Pixel_7' })
+```
+
+## API Reference
+
+### `run(entry[, options]) -> Promise<any>`
+
+Options:
+
+- `base` (string)
+- `host` (string)
+- `device` (string)
+
+## CLI
+
+```bash
+bare-run index.js
+```
+
+## Complete Examples
+
+### Example 1: Desktop Run
+
+```js
+const run = require('bare-run')
+
+await run('index.js')
+```
+
+### Example 2: Android Device
+
+```js
+const run = require('bare-run')
+
+await run('app.js', { host: 'android-arm64', device: 'Pixel_7' })
+```
+
+### Example 3: iOS Simulator
+
+```js
+const run = require('bare-run')
+
+await run('app.js', { host: 'ios-arm64-simulator', device: 'iPhone 15' })
+```
+
+## Best Practices
+
+- **Set `host` explicitly** when targeting non-host platforms.
+- **Use device names** that match platform tooling.
+
+## Performance Notes
+
+- Bundle creation adds overhead; cache bundles if running repeatedly.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Tooling | **Ecosystem Role**: Cross-platform Runner | **Dependencies**: bare-pack

modules/bare-runtime.md

@@ -0,0 +1,85 @@
+# bare-runtime - Prebuilt Bare Binaries
+
+## Overview
+
+bare-runtime provides prebuilt Bare binaries for multiple platforms. It returns the path to the appropriate binary and includes a `spawn` helper for launching it.
+
+### Key Features
+
+- **Multi-platform**: macOS, iOS, Linux, Android, Windows.
+- **Runtime lookup**: Resolve correct binary for platform/arch.
+- **Spawn helper**: Launch binaries with proper permissions.
+
+### Use Cases
+
+- **Embedding Bare**: Use prebuilt runtime binaries in tooling.
+- **CLI convenience**: Spawn the correct binary automatically.
+
+## Installation
+
+```bash
+npm install bare-runtime
+```
+
+## Quick Start
+
+```js
+const runtime = require('bare-runtime')
+
+const path = runtime()
+```
+
+## API Reference
+
+### `runtime([referrer][, options]) -> string`
+
+Options:
+
+- `platform` (default `process.platform`)
+- `arch` (default `process.arch`)
+
+### `bare-runtime/spawn`
+
+Spawns the runtime binary as a child process with optional `args`.
+
+## Complete Examples
+
+### Example 1: Resolve Binary
+
+```js
+const runtime = require('bare-runtime')
+
+console.log(runtime())
+```
+
+### Example 2: Cross Target
+
+```js
+const runtime = require('bare-runtime')
+
+console.log(runtime({ platform: 'linux', arch: 'x64' }))
+```
+
+### Example 3: Spawn
+
+```js
+const spawn = require('bare-runtime/spawn')
+
+const child = spawn({ args: ['--version'] })
+```
+
+## Best Practices
+
+- **Pin versions** to match your Bare runtime.
+- **Handle missing binaries** with try/catch.
+
+## Performance Notes
+
+- Lookup is cheap; actual runtime cost depends on binary.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Runtime Utility | **Ecosystem Role**: Binary Distribution | **Dependencies**: platform prebuilds

modules/bare-sidecar.md

@@ -0,0 +1,92 @@
+# bare-sidecar - Sidecar Process Manager
+
+## Overview
+
+bare-sidecar spawns and manages a Bare sidecar process from Node.js or Electron. It exposes a Duplex stream connected to the sidecar IPC channel and provides access to stdio streams.
+
+### Key Features
+
+- **Process spawn**: Launch Bare with an entrypoint.
+- **IPC channel**: Duplex stream over an extra stdio pipe.
+- **Stdio access**: Exposes `stdin`, `stdout`, `stderr`.
+
+### Use Cases
+
+- **Background workers**: Run Bare code alongside Node/Electron.
+- **IPC bridging**: Exchange binary messages with a sidecar.
+
+## Installation
+
+```bash
+npm install bare-sidecar
+```
+
+## Quick Start
+
+```js
+const Sidecar = require('bare-sidecar')
+
+const sidecar = new Sidecar('./entry')
+sidecar.on('data', console.log).write('Hello sidecar')
+```
+
+## API Reference
+
+### `new Sidecar(entry[, args][, opts])`
+
+- `entry`: Script entrypoint
+- `args`: Array of args
+
+### Properties
+
+- `stdin`, `stdout`, `stderr`
+
+### Events
+
+- `exit`, `close`, `error`
+
+## Complete Examples
+
+### Example 1: IPC Messaging
+
+```js
+const Sidecar = require('bare-sidecar')
+
+const sc = new Sidecar('./worker')
+sc.on('data', (buf) => console.log(buf))
+sc.write(Buffer.from('ping'))
+```
+
+### Example 2: Pipe stdout
+
+```js
+const Sidecar = require('bare-sidecar')
+
+const sc = new Sidecar('./worker')
+sc.stdout.pipe(process.stdout)
+```
+
+### Example 3: Handle Exit
+
+```js
+const Sidecar = require('bare-sidecar')
+
+const sc = new Sidecar('./worker')
+sc.on('exit', (code) => console.log(code))
+```
+
+## Best Practices
+
+- **Handle errors** from the sidecar stream.
+- **Shutdown gracefully** by ending the stream.
+
+## Performance Notes
+
+- IPC throughput depends on pipe buffering and message size.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Runtime Utility | **Ecosystem Role**: Sidecar Management | **Dependencies**: child_process

modules/bare-storage.md

@@ -0,0 +1,86 @@
+# bare-storage - Cross-platform Storage Paths
+
+## Overview
+
+bare-storage provides OS-specific directory locations for persistent and ephemeral storage. It exposes intent-based helpers for data and cache directories.
+
+### Key Features
+
+- **Persistent**: Data that should survive restarts.
+- **Ephemeral**: Cache/temp data that can be wiped.
+- **Cross-platform**: OS-specific paths for Bare.
+
+### Use Cases
+
+- **App data**: Store user data in persistent directories.
+- **Cache**: Use ephemeral storage for temporary files.
+
+## Installation
+
+```bash
+npm install bare-storage
+```
+
+## Quick Start
+
+```js
+const dir = require('bare-storage')
+
+const data = dir.persistent()
+const cache = dir.ephemeral()
+```
+
+## API Reference
+
+### `persistent() -> string`
+
+Returns a normalized absolute path for durable storage.
+
+### `ephemeral() -> string`
+
+Returns a normalized absolute path for cache/temp data.
+
+## Complete Examples
+
+### Example 1: Save Data
+
+```js
+const dir = require('bare-storage')
+const fs = require('bare-fs')
+
+const path = dir.persistent() + '/settings.json'
+fs.writeFileSync(path, JSON.stringify({ ok: true }))
+```
+
+### Example 2: Cache File
+
+```js
+const dir = require('bare-storage')
+
+const cache = dir.ephemeral() + '/tmp.bin'
+```
+
+### Example 3: Log Locations
+
+```js
+const dir = require('bare-storage')
+
+console.log(dir.persistent())
+console.log(dir.ephemeral())
+```
+
+## Best Practices
+
+- **Use persistent** for user data and config.
+- **Use ephemeral** for caches that can be wiped safely.
+
+## Performance Notes
+
+- Path lookups are fast; IO depends on underlying storage.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Utility | **Ecosystem Role**: Storage Paths | **Dependencies**: OS-specific backends

modules/bare-string-decoder.md

@@ -0,0 +1,78 @@
+# bare-string-decoder - string_decoder Shim
+
+## Overview
+
+bare-string-decoder provides a `StringDecoder` compatible with Node's `string_decoder`, implemented via `text-decoder` for Bare.
+
+### Key Features
+
+- **Node-compatible API**: `StringDecoder` class.
+- **Text decoding**: Works with Buffer and Uint8Array data.
+
+### Use Cases
+
+- **Stream decoding**: Convert byte chunks to strings.
+- **Compatibility**: Satisfy dependencies expecting `string_decoder`.
+
+## Installation
+
+```bash
+npm install bare-string-decoder
+```
+
+## Quick Start
+
+```js
+const { StringDecoder } = require('bare-string-decoder')
+
+const decoder = new StringDecoder('utf8')
+console.log(decoder.write(Buffer.from('hello')))
+```
+
+## API Reference
+
+### `const { StringDecoder } = require('bare-string-decoder')`
+
+Re-exports `StringDecoder` from `text-decoder`.
+
+## Complete Examples
+
+### Example 1: Decode Chunks
+
+```js
+const { StringDecoder } = require('bare-string-decoder')
+
+const dec = new StringDecoder('utf8')
+console.log(dec.write(Buffer.from('he')))
+console.log(dec.write(Buffer.from('llo')))
+```
+
+### Example 2: End Flush
+
+```js
+const { StringDecoder } = require('bare-string-decoder')
+
+const dec = new StringDecoder('utf8')
+dec.write(Buffer.from([0xe2, 0x82]))
+console.log(dec.end(Buffer.from([0xac])))
+```
+
+### Example 3: Stream Usage
+
+```js
+const { StringDecoder } = require('bare-string-decoder')
+
+const dec = new StringDecoder('utf8')
+stream.on('data', (chunk) => console.log(dec.write(chunk)))
+```
+
+## Best Practices
+
+- **Use `end()`** to flush incomplete multibyte sequences.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Shim | **Ecosystem Role**: Text Decoding | **Dependencies**: text-decoder

modules/bare-structured-clone.md

@@ -0,0 +1,136 @@
+# bare-structured-clone - Structured Cloning
+
+## Overview
+
+bare-structured-clone implements the HTML structured clone algorithm for Bare. It supports serialization/deserialization of a wide range of types, transferables, and custom serializable interfaces.
+
+### Key Features
+
+- **Spec-aligned**: Based on the WHATWG structured clone algorithm.
+- **Transferables**: ArrayBuffer and custom transferable support.
+- **Custom interfaces**: Register serializable/transferable classes.
+- **Binary encoding**: Uses `compact-encoding` for transport.
+
+### Use Cases
+
+- **Worker messaging**: Clone data for thread boundaries.
+- **Storage**: Serialize complex objects safely.
+- **IPC**: Transfer objects with custom types.
+
+## Installation
+
+```bash
+npm install bare-structured-clone
+```
+
+## Quick Start
+
+```js
+const structuredClone = require('bare-structured-clone')
+
+const copy = structuredClone({ hello: 'world' })
+```
+
+## API Reference
+
+### `structuredClone(value[, opts])`
+
+Clone a value using structured cloning.
+
+**Options:**
+- `transfer` (Array): Transfer list.
+- `interfaces` (Array<Constructor>): Custom serializable/transferable types.
+
+### `serialize(value[, forStorage, interfaces])`
+### `deserialize(serialized[, interfaces])`
+
+Serialize/deserialize without transfer.
+
+### `serializeWithTransfer(value[, transferList, interfaces])`
+### `deserializeWithTransfer(serialized[, interfaces])`
+
+Serialize/deserialize with transferables.
+
+### `constants`, `errors`, `symbols`
+
+Access internal constants, errors, and symbol keys:
+
+- `symbols.serialize`
+- `symbols.deserialize`
+- `symbols.detach`
+- `symbols.attach`
+
+### `Serializable` / `Transferable`
+
+Base classes for custom types.
+
+## Complete Examples
+
+### Example 1: Basic Clone
+
+```js
+const clone = require('bare-structured-clone')
+
+const obj = { a: 1, b: new Date() }
+const copy = clone(obj)
+```
+
+### Example 2: Transfer ArrayBuffer
+
+```js
+const clone = require('bare-structured-clone')
+
+const buf = new ArrayBuffer(8)
+const res = clone.serializeWithTransfer({ buf }, [buf])
+const obj = clone.deserializeWithTransfer(res)
+```
+
+### Example 3: Custom Serializable
+
+```js
+const sc = require('bare-structured-clone')
+
+class Point extends sc.Serializable {
+  constructor(x, y) { super(); this.x = x; this.y = y }
+  [sc.symbols.serialize]() { return { x: this.x, y: this.y } }
+  static [sc.symbols.deserialize](data) { return new Point(data.x, data.y) }
+}
+
+const p = new Point(1, 2)
+const res = sc.serialize(p, false, [Point])
+const copy = sc.deserialize(res, [Point])
+```
+
+### Example 4: Storage Mode
+
+```js
+const sc = require('bare-structured-clone')
+
+const serialized = sc.serialize({ ok: true }, true)
+```
+
+## Best Practices
+
+- **Register interfaces** for custom classes you need to clone.
+- **Use transfer list** for large buffers to avoid copies.
+- **Handle errors** for unsupported types (e.g., functions, symbols).
+
+## Performance Notes
+
+- Large graphs incur serialization overhead; transferables reduce copies.
+
+## Security Considerations
+
+- Do not deserialize untrusted payloads without validation.
+
+## Error Handling
+
+- Throws `errors.UNSERIALIZABLE_TYPE` for unsupported values.
+- Throws `errors.INVALID_INTERFACE` if interface registration is missing.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Serialization | **Ecosystem Role**: Structured Clone | **Dependencies**: compact-encoding, bare-type

modules/bare-unpack.md

@@ -0,0 +1,95 @@
+# bare-unpack - Bundle Unpacking
+
+## Overview
+
+bare-unpack extracts files from a Bare bundle. It can write selected files to external storage and rebuild a new bundle with rewritten import paths for extracted files.
+
+### Key Features
+
+- **Selective extraction**: Control files, addons, and assets.
+- **Repack support**: Returns a new bundle with rewritten paths.
+- **CLI**: Unpack bundles to disk.
+
+### Use Cases
+
+- **Deployment**: Extract assets or addons separately.
+- **Debugging**: Inspect bundle contents.
+
+## Installation
+
+```bash
+npm install bare-unpack
+```
+
+## Quick Start
+
+```js
+const unpack = require('bare-unpack')
+
+const repacked = await unpack(bundle, async (key) => `/tmp/${key}`)
+```
+
+## API Reference
+
+### `unpack(bundle[, options], writeFile) -> Promise<Bundle>`
+
+Options:
+
+- `files` (boolean)
+- `addons` (boolean)
+- `assets` (boolean)
+- `concurrency` (number)
+
+### CLI
+
+```bash
+bare-unpack --out ./out app.bundle
+```
+
+## Complete Examples
+
+### Example 1: Extract All
+
+```js
+const unpack = require('bare-unpack')
+
+await unpack(bundle, async (key) => `/tmp/${key}`)
+```
+
+### Example 2: Extract Only Addons
+
+```js
+const unpack = require('bare-unpack')
+
+await unpack(bundle, { files: false, addons: true }, async (key) => `/tmp/${key}`)
+```
+
+### Example 3: Custom Rewrite
+
+```js
+const unpack = require('bare-unpack')
+
+const repacked = await unpack(bundle, async (key) => `/opt/resources/${key}`)
+```
+
+### Example 4: CLI
+
+```bash
+bare-unpack --out ./out app.bundle
+```
+
+## Best Practices
+
+- **Preserve directory structure** when writing extracted files.
+- **Handle rewrites** if you extract addons or assets.
+
+## Performance Notes
+
+- Extraction is IO-bound; concurrency can improve throughput.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Tooling | **Ecosystem Role**: Bundle Extraction | **Dependencies**: bare-bundle

modules/bare-utils.md

@@ -0,0 +1,80 @@
+# bare-utils - Node-compatible Utilities
+
+## Overview
+
+bare-utils provides a subset of Node's `util` module for Bare, including `format`, `inspect`, `promisify`, `types`, and text encoding helpers.
+
+### Key Features
+
+- **Formatting**: `format`, `formatWithOptions`.
+- **Inspection**: `inspect` with Bare styling.
+- **Promisify**: Convert callback APIs to promises.
+- **Types**: Type checks compatible with Node's `util.types`.
+
+### Use Cases
+
+- **Compatibility**: Run Node-targeted libraries in Bare.
+- **Utility helpers**: Common formatting and type operations.
+
+## Installation
+
+```bash
+npm install bare-utils
+```
+
+## Quick Start
+
+```js
+const util = require('bare-utils')
+
+console.log(util.format('Hello %s', 'world'))
+```
+
+## API Reference
+
+Exports:
+
+- `TextEncoder`, `TextDecoder`
+- `debuglog`
+- `format`, `formatWithOptions`
+- `inspect`
+- `deprecate`, `inherits`, `promisify`, `types`
+
+## Complete Examples
+
+### Example 1: Format
+
+```js
+const util = require('bare-utils')
+
+util.format('value=%d', 42)
+```
+
+### Example 2: Promisify
+
+```js
+const util = require('bare-utils')
+
+const fn = util.promisify((cb) => cb(null, 1))
+console.log(await fn())
+```
+
+### Example 3: Types
+
+```js
+const util = require('bare-utils')
+
+console.log(util.types.isDate(new Date()))
+```
+
+## Best Practices
+
+- **Use util.types** for robust type checking.
+- **Avoid heavy inspect** on large objects in hot paths.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Utility | **Ecosystem Role**: Node Compatibility | **Dependencies**: bare-encoding, bare-format

modules/bare-v8-to-istanbul.md

@@ -0,0 +1,63 @@
+# bare-v8-to-istanbul - Coverage Converter Wrapper
+
+## Overview
+
+bare-v8-to-istanbul wraps `v8-to-istanbul` to work inside Bare by temporarily swapping `global.process` to `bare-process` when necessary.
+
+### Key Features
+
+- **Compatibility wrapper**: Works in Bare environments.
+- **Drop-in**: Exposes the `v8-to-istanbul` API.
+
+### Use Cases
+
+- **Coverage reporting**: Convert V8 coverage to Istanbul format.
+- **Tooling**: Use coverage libraries inside Bare.
+
+## Installation
+
+```bash
+npm install bare-v8-to-istanbul
+```
+
+## Quick Start
+
+```js
+const v8toIstanbul = require('bare-v8-to-istanbul')
+
+const converter = v8toIstanbul('/path/to/file.js')
+```
+
+## API Reference
+
+This module re-exports `v8-to-istanbul` and its API.
+
+## Complete Examples
+
+### Example 1: Create Converter
+
+```js
+const v8toIstanbul = require('bare-v8-to-istanbul')
+
+const converter = v8toIstanbul('index.js')
+```
+
+### Example 2: Load Coverage
+
+```js
+const v8toIstanbul = require('bare-v8-to-istanbul')
+
+const converter = v8toIstanbul('index.js')
+await converter.load()
+```
+
+## Best Practices
+
+- **Use in tooling** rather than runtime hot paths.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Tooling | **Ecosystem Role**: Coverage | **Dependencies**: v8-to-istanbul, bare-process

modules/bare-v8.md

@@ -0,0 +1,68 @@
+# bare-v8 - V8 Utilities
+
+## Overview
+
+bare-v8 exposes a small set of V8 metrics for Bare, including heap statistics and heap space statistics.
+
+### Key Features
+
+- **Heap stats**: `getHeapStatistics()`.
+- **Heap spaces**: `getHeapSpaceStatistics()`.
+
+### Use Cases
+
+- **Memory monitoring**: Track heap usage.
+- **Diagnostics**: Inspect space utilization.
+
+## Installation
+
+```bash
+npm install bare-v8
+```
+
+## Quick Start
+
+```js
+const v8 = require('bare-v8')
+
+console.log(v8.getHeapStatistics())
+```
+
+## API Reference
+
+### `getHeapStatistics() -> object`
+
+Returns an object with V8 heap statistics.
+
+### `getHeapSpaceStatistics() -> object[]`
+
+Returns per-space statistics for the V8 heap.
+
+## Complete Examples
+
+### Example 1: Heap Statistics
+
+```js
+const v8 = require('bare-v8')
+
+const stats = v8.getHeapStatistics()
+```
+
+### Example 2: Heap Spaces
+
+```js
+const v8 = require('bare-v8')
+
+const spaces = v8.getHeapSpaceStatistics()
+```
+
+## Best Practices
+
+- **Sample periodically** to avoid noisy metrics.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Diagnostics | **Ecosystem Role**: V8 Metrics | **Dependencies**: native binding

modules/bare-vm.md

@@ -0,0 +1,83 @@
+# bare-vm - VM Contexts for Bare
+
+## Overview
+
+bare-vm provides a Node-like `vm` API using `bare-realm`. It supports creating contexts and running code in isolated environments.
+
+### Key Features
+
+- **Contexts**: `createContext()` builds isolated globals.
+- **Execution**: `runInContext` and `runInNewContext`.
+
+### Use Cases
+
+- **Sandboxing**: Execute untrusted code in a separate context.
+- **Testing**: Run scripts in isolated environments.
+
+## Installation
+
+```bash
+npm install bare-vm
+```
+
+## Quick Start
+
+```js
+const vm = require('bare-vm')
+
+const ctx = vm.createContext()
+vm.runInContext('x = 40; x += 2', ctx)
+```
+
+## API Reference
+
+### `createContext() -> object`
+
+Creates a new realm-backed context.
+
+### `runInContext(code, context[, options])`
+
+Executes code inside an existing context.
+
+### `runInNewContext(code[, options])`
+
+Creates a context and runs code in it.
+
+## Complete Examples
+
+### Example 1: Context Execution
+
+```js
+const vm = require('bare-vm')
+
+const ctx = vm.createContext()
+vm.runInContext('x = 1', ctx)
+```
+
+### Example 2: New Context
+
+```js
+const vm = require('bare-vm')
+
+const result = vm.runInNewContext('1 + 1')
+```
+
+### Example 3: Filename Metadata
+
+```js
+const vm = require('bare-vm')
+
+vm.runInNewContext('throw new Error("boom")', { filename: 'sandbox.js' })
+```
+
+## Best Practices
+
+- **Avoid sharing objects** between contexts.
+- **Use filenames** to improve stack traces.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Runtime Utility | **Ecosystem Role**: Sandbox | **Dependencies**: bare-realm

modules/bare-which.md

@@ -0,0 +1,84 @@
+# bare-which - Locate Executables
+
+## Overview
+
+bare-which finds executables in the system PATH, based on `node-which`. It supports async and sync APIs, Windows PATHEXT handling, and optional multiple results.
+
+### Key Features
+
+- **Cross-platform**: Handles Windows PATHEXT.
+- **Async and sync**: `which()` and `which.sync()`.
+- **Multiple results**: `all` option returns all matches.
+
+### Use Cases
+
+- **CLI tooling**: Locate external commands.
+- **Build scripts**: Verify tool availability.
+
+## Installation
+
+```bash
+npm install bare-which
+```
+
+## Quick Start
+
+```js
+const which = require('bare-which')
+
+const path = await which('ping')
+```
+
+## API Reference
+
+### `await which(cmd[, options])`
+
+Options:
+
+- `path` (string)
+- `pathExt` (string)
+- `delimiter` (string)
+- `all` (boolean)
+- `nothrow` (boolean)
+
+### `which.sync(cmd[, options])`
+
+Synchronous variant.
+
+## Complete Examples
+
+### Example 1: Basic Lookup
+
+```js
+const which = require('bare-which')
+
+console.log(await which('node'))
+```
+
+### Example 2: All Matches
+
+```js
+const which = require('bare-which')
+
+const all = await which('python', { all: true })
+```
+
+### Example 3: Sync
+
+```js
+const which = require('bare-which')
+
+const path = which.sync('git')
+```
+
+## Best Practices
+
+- **Set `nothrow`** if missing commands are acceptable.
+- **Use `all`** when multiple PATH entries are relevant.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Utility | **Ecosystem Role**: CLI Support | **Dependencies**: which-runtime

modules/bare-ws.md

@@ -0,0 +1,85 @@
+# bare-ws - WebSocket Library
+
+## Overview
+
+bare-ws provides WebSocket client and server implementations for Bare. It exposes `Server` and `Socket` classes with a stream-like API.
+
+### Key Features
+
+- **WebSocket server**: `new ws.Server({ port })`.
+- **WebSocket client**: `new ws.Socket({ port, host })`.
+- **Stream interface**: Read/write data via events.
+
+### Use Cases
+
+- **Realtime apps**: Bidirectional communication.
+- **Local testing**: Lightweight WebSocket server in Bare.
+
+## Installation
+
+```bash
+npm install bare-ws
+```
+
+## Quick Start
+
+```js
+const ws = require('bare-ws')
+
+const server = new ws.Server({ port: 8080 }, (socket) => {
+  socket.on('data', (data) => console.log(data.toString()))
+})
+```
+
+## API Reference
+
+### `new ws.Server(opts[, onconnection])`
+
+- `opts.port` (number)
+- `onconnection(socket)` callback
+
+### `new ws.Socket(opts)`
+
+- `opts.port`, `opts.host`
+
+## Complete Examples
+
+### Example 1: Echo Server
+
+```js
+const ws = require('bare-ws')
+
+const server = new ws.Server({ port: 8080 }, (socket) => {
+  socket.on('data', (data) => socket.write(data))
+})
+```
+
+### Example 2: Client
+
+```js
+const ws = require('bare-ws')
+
+const socket = new ws.Socket({ port: 8080 })
+socket.write('hello')
+```
+
+### Example 3: Listen Event
+
+```js
+const ws = require('bare-ws')
+
+const server = new ws.Server({ port: 8080 })
+server.on('listening', () => console.log('ready'))
+```
+
+## Best Practices
+
+- **Handle close/error** events on sockets.
+- **Limit message sizes** for untrusted peers.
+
+## License
+
+Apache-2.0
+
+---
+**Module Type**: Networking | **Ecosystem Role**: WebSocket | **Dependencies**: internal ws libs