snxraven/bare-operating-system
1
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Update Docs

Browse Source
This commit is contained in:
Raven Scott
2026-04-06 06:31:59 -04:00
parent 140b17c5fd
commit 6d0d1b8049
39 changed files with 1041 additions and 596 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DOCUMENTATION.md
+5 -2
View File
@@ -1,6 +1,8 @@
# Documentation
Start at the **[documentation home](docs/README.md)** for role-based navigation (run, understand, extend, specify). This file keeps a **legacy map** from the former single-file inventory to the split reference topics.
Start at the **[documentation home](docs/README.md)** for role-based navigation (run, understand, extend, specify), **time-boxed paths** (“Pick your depth”), and the **POSIX + P2P** dashboard. Short evergreen explainers live under **[docs/concepts/](docs/concepts/README.md)** (two drives, boot timeline, swarm, identity, POSIX stance).
This file keeps a **legacy map** from the former single-file inventory to the split reference topics below.
> **Note**
> Canonical **terminology**: [docs/glossary.md](docs/glossary.md). **FAQ** and **troubleshooting router**: [docs/faq.md](docs/faq.md), [docs/troubleshooting.md](docs/troubleshooting.md).
@@ -11,7 +13,8 @@ Start at the **[documentation home](docs/README.md)** for role-based navigation
| Goal | Link |
| --- | --- |
| Documentation hub (full map) | [docs/README.md](docs/README.md) |
| Documentation hub (full map, curricula) | [docs/README.md](docs/README.md) |
| Evergreen concepts (two drives, boot, P2P) | [docs/concepts/README.md](docs/concepts/README.md) |
| Run the system | [users-manual/README.md](users-manual/README.md) |
| Architecture narrative | [handbook/README.md](handbook/README.md) |
| Extend `/bin`, `ctx`, Pear | [developer-guide/README.md](developer-guide/README.md) |
README.md
+71 -54
View File
@@ -1,54 +1,24 @@
# Bare operating system
A **P2P-first** system image: the OS lives in a **Hyperdrive** that peers **replicate from the swarm** (Hyperswarm + Protomux), not from a single HTTP mirror. A **Bare**/**Pear** **seeder** stages the kernel and `/bin` straight from the repo into the drive; a **booter** discovers peers, reads the **MBR**, opens the system drive, and runs **`/boot/init.js`**. A separate **personal** Hyperdrive holds per-node state (identity, history, vault). The stack is built for **decentralized distribution** of the image alongside Holepunch-style runtimes.
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](package.json)
This project is **experimental research software**, not a production OS.
> [!CAUTION]
> **Experimental research software** — not a production OS. Treat keys, vault data, and network exposure accordingly.
## What you get
**Bare OS** is a **P2P-first** system image: the operating tree lives on a **Hyperdrive** replicated over **Hyperswarm** and **Protomux**, not a single HTTP mirror. A **seeder** stages the kernel and **`/bin`** into the system drive and publishes the **MBR**; a **booter** discovers peers, replicates the image, attaches a **personal** drive for identity and mutable state, and runs **`/boot/init.js`**. The stack targets **decentralized distribution** alongside Holepunch-style runtimes (Bare / Pear).
- **Two-drive model** — read-only **system** image + writable **personal** namespace; VFS routes `$HOME` and `/.bare/` to the personal drive.
- **Tier-1 `/bin`** — **149** POSIX-oriented utilities (authoritative list: **`COREUTILS_COMMANDS`** in [`packages/bare-os-coreutils/lib/commands.mjs`](packages/bare-os-coreutils/lib/commands.mjs); **`verify-man-coverage`** in **`pretest`** keeps **`man.json`** in sync), line shell with pipelines and redirects, **`sed`**/**`awk`**, **`man`** backed by a merged JSON handbook + coreutils pages.
- **Identity** — Ed25519 account on the personal drive, guest vs unlocked session, encrypted vault snapshot (`savevault` / `logout --save`).
- **Boot plumbing** — initd/cron **themes**, synthetic `/proc` / `/run` / `/sys`, optional **`ctx.bare`** bundles from **`/lib/bare`** (Holepunch catalog workflow at repo root).
- **Protocol** — Swarm topic + Protomux **`bare-os-v1`**, 512-byte **MBR** with Hyperdrive keys (`BIOS` magic). Details: [handbook chapter 3](handbook/03-protocol-and-disk.md) and [protocol reference](docs/reference/package-bare-os-protocol.md).
<details>
<summary><strong>60-second mental model</strong></summary>
## Documentation
- **System drive** — replicated image: **`/boot`**, **`/bin`**, stock kernel, read-only policy for most tree.
- **Personal drive** — **`$HOME`**, **`/.bare`**, vault material, per-node history.
- **Dev workflow** — almost always **two processes**: seeder (publisher) + booter (consumer) in two terminals.
- **Two runtimes** — the **host** (Node / Pear) implements **`ctx`** and the VFS; **scripts on the drive** run under the in-image eval model (not Node ESM on-disk). See [Developer guide §1 — Two runtimes](developer-guide/01-two-runtimes-host-vs-image.md).
**Start here:** [Documentation home](docs/README.md) — role-based map of every tree (user manual, handbook, developer guide, reference), including an **architecture snapshot** diagram for the swarm → booter → image path.
</details>
**On this page:** [User manual](#user-manual) · [Handbook](#handbook) · [Developer guide](#developer-guide) · [Reference and contracts](#reference-and-contracts) · [Glossary and help](#glossary-and-help) · [POSIX surface](#posix-surface)
### User manual
Start here if you want to **run and use** Bare OS without reading the full architecture first: [users-manual/README.md](users-manual/README.md). It covers install, seeder and booter, shell basics, identity and vault at a practical level, `man` / `help`, troubleshooting, and links into deeper docs.
### Handbook
The [handbook](handbook/README.md) is the **narrative spine**—why the system is shaped this way, how the protocol and booter fit together, and what to expect from POSIX-like behavior. Begin with the [Preface](handbook/00-preface.md) for thesis and contributor paths, or jump to [Chapter 7 — Operations](handbook/07-operations-and-development.md) when you only care about CI, Pear, and env vars.
### Developer guide
The [developer guide](developer-guide/README.md) is the **how-to** for `start(ctx)` / `run(ctx, argv)`, extending `/bin`, testing, Pear integration, telemetry scrubbing, and security boundaries.
### Reference and contracts
- **[Documentation hub](docs/README.md)** — full navigation map, themes, Holepunch catalog, ADRs, release checklist.
- **[File-level reference](docs/reference/README.md)** — package paths, environment appendix, data-flow diagram (legacy map: [`DOCUMENTATION.md`](DOCUMENTATION.md)).
- **[`ctx` API changelog](packages/bare-os-booter/CHANGELOG.md)** — **`bareOsCtxApiVersion`** history for kernels and scripts that depend on booter behavior.
- **[Compatibility matrix](docs/reference/compatibility-matrix.md)** — protocol, feature-bits doc, ctx API, and telemetry schema versions in one place.
### Glossary and help
- **[Glossary](docs/glossary.md)** — canonical definitions used across all trees.
- **[FAQ](docs/faq.md)** — cross-cutting questions with pointers to deep docs.
- **[Troubleshooting](docs/troubleshooting.md)** — symptom → doc router.
- **[Contributing to docs](docs/CONTRIBUTING-DOCS.md)** — style, Mermaid, link checks, terminology rules.
### POSIX surface
Intentional coverage and gaps for utilities, shell, and VFS: [handbook — Chapter 9](handbook/09-posix-utilities-shell-and-vfs.md). Declared profile **`1.0.19`** (**`BARE_OS_POSIX_PROFILE_VERSION`**) with **`ctx`** API **`1.54.0`** — see [POSIX declared profile](docs/architecture/POSIX_DECLARED_PROFILE.md) and [compatibility matrix](docs/reference/compatibility-matrix.md). Machine-readable summary: [docs/reference/posix-compliance-matrix.json](docs/reference/posix-compliance-matrix.json) (verified in **`pretest`**).
## Quick start
## Try it
```bash
git clone https://git.ssh.surf/snxraven/bare-operating-system.git
@@ -56,19 +26,64 @@ cd bare-operating-system
npm ci
```
**Seeder** (publishes the drive + MBR; run from repo root so `kernel/` resolves):
**Terminal A — seeder** (publishes the drive + MBR; `npm run os:*` uses **Pear**):
```bash
npm run os:seeder
```
**Booter** (joins the swarm, boots the image — use another terminal):
**Terminal B — booter**:
```bash
npm run os:booter
```
With **Pear** installed, from the repo root: `npm run os:seeder` and `npm run os:booter` link workspace `node_modules` then `pear run --dev` each app. Full operations, env vars, and troubleshooting: [handbook ch.7](handbook/07-operations-and-development.md) and [environment reference](docs/reference/environment-and-posix-appendix.md).
> [!TIP]
> **`npm run os:seeder`** and **`npm run os:booter`** run **`pear run --dev`** after linking hoisted workspace dependencies. For a **Node-only** path (no Pear), see [User manual — Chapter 3](users-manual/03-running-seeder-and-booter.md).
Full operations, environment variables, and troubleshooting: [Handbook — Chapter 7](handbook/07-operations-and-development.md) and [Environment appendix](docs/reference/environment-and-posix-appendix.md).
## Documentation
**Start here:** [Documentation home](docs/README.md) — role-based map, contract spine, and **POSIX + P2P** dashboard links.
**Evergreen concepts** (two drives, boot, swarm, identity, POSIX stance): [docs/concepts/README.md](docs/concepts/README.md)
**On this page:** [What you get](#what-you-get) · [User manual](#user-manual) · [Handbook](#handbook) · [Developer guide](#developer-guide) · [Reference](#reference-and-contracts) · [POSIX surface](#posix-surface) · [Protocol](#protocol-snapshot) · [Kernel parity](#kernel-image-and-pear-seeder-parity) · [Contributing](#contributing--ci)
### What you get
- **Two-drive model** — read-only **system** image + writable **personal** namespace; VFS routes **`$HOME`** and **`/.bare/`** to the personal drive.
- **Tier-1 `/bin`** — **149** POSIX-oriented utilities (authoritative list: **`COREUTILS_COMMANDS`** in [`packages/bare-os-coreutils/lib/commands.mjs`](packages/bare-os-coreutils/lib/commands.mjs); **`verify-man-coverage`** in **`pretest`** keeps **`man.json`** in sync), line shell with pipelines and redirects, **`sed`**/**`awk`**, **`man`** backed by merged JSON handbook + coreutils pages.
- **Identity** — Ed25519 account on the personal drive, guest vs unlocked session, encrypted vault snapshot (`savevault` / `logout --save`).
- **Boot plumbing** — initd/cron **themes**, synthetic **`/proc`** / **`/run`** / **`/sys`**, optional **`ctx.bare`** bundles from **`/lib/bare`** (Holepunch catalog workflow at repo root).
- **Protocol** — Swarm topic + Protomux **`bare-os-v1`**, 512-byte **MBR** with Hyperdrive keys (`BIOS` magic). Details: [Handbook — Chapter 3](handbook/03-protocol-and-disk.md) and [Protocol reference](docs/reference/package-bare-os-protocol.md).
### User manual
For **run and use** without reading full architecture first: [users-manual/README.md](users-manual/README.md) — install, seeder and booter, shell, identity, `man` / `help`, troubleshooting.
### Handbook
Narrative spine — *why* the system is shaped this way: [handbook/README.md](handbook/README.md). Begin with [Preface](handbook/00-preface.md) or [Chapter 7 — Operations](handbook/07-operations-and-development.md) for CI and Pear.
### Developer guide
How-to for **`start(ctx)`** / **`run(ctx, argv)`**, extending **`/bin`**, testing, Pear, telemetry scrubbing: [developer-guide/README.md](developer-guide/README.md).
### Reference and contracts
- **[File-level reference](docs/reference/README.md)** — packages, environment appendix, data flow (legacy map: [`DOCUMENTATION.md`](DOCUMENTATION.md)).
- **[`ctx` API changelog](packages/bare-os-booter/CHANGELOG.md)** — **`bareOsCtxApiVersion`** history.
- **[Compatibility matrix](docs/reference/compatibility-matrix.md)** — protocol, feature-bits doc, **`ctx`** API, lifecycle/telemetry schema versions.
### Glossary and help
[Glossary](docs/glossary.md) · [FAQ](docs/faq.md) · [Troubleshooting](docs/troubleshooting.md) · [Contributing to docs](docs/CONTRIBUTING-DOCS.md)
### POSIX surface
[Handbook — Chapter 9](handbook/09-posix-utilities-shell-and-vfs.md). Declared profile **`1.0.19`** (**`BARE_OS_POSIX_PROFILE_VERSION`**) with **`ctx`** API **`1.54.0`** — [POSIX declared profile](docs/architecture/POSIX_DECLARED_PROFILE.md) and [compatibility matrix](docs/reference/compatibility-matrix.md). Machine-readable: [docs/reference/posix-compliance-matrix.json](docs/reference/posix-compliance-matrix.json) (verified in **`pretest`**).
## Protocol snapshot
@@ -76,28 +91,30 @@ With **Pear** installed, from the repo root: `npm run os:seeder` and `npm run os
- **Protomux channel name** — `bare-os-v1`
- **MBR** — 512 bytes, magic `BIOS`, primary Hyperdrive key at byte offset 8, failover keys at offsets 40 and 72
Full wire layout and replication behavior: [handbook — Chapter 3](handbook/03-protocol-and-disk.md) and [protocol package reference](docs/reference/package-bare-os-protocol.md).
Full wire layout: [Handbook — Chapter 3](handbook/03-protocol-and-disk.md) and [protocol package reference](docs/reference/package-bare-os-protocol.md).
## Guest identity (short)
Default session is **guest**; **`login` / `logout`**, **`/.bare/account`**, guest **`/.bare`** read policy, legacy-root migration (**`BARE_OS_PERSONAL_ROOT_MIGRATE`**), and optional **`BARE_OS_PERSONAL_ACCT_PREFIX`** are documented in the [booter reference](docs/reference/package-bare-os-booter.md) (§§12.8–12.9), [environment appendix](docs/reference/environment-and-posix-appendix.md), and [handbook ch.4](handbook/04-the-booter-runtime.md).
Default session is **guest**; **`login` / `logout`**, **`/.bare/account`**, guest **`/.bare`** read policy, legacy-root migration (**`BARE_OS_PERSONAL_ROOT_MIGRATE`**), and optional **`BARE_OS_PERSONAL_ACCT_PREFIX`**: [booter reference](docs/reference/package-bare-os-booter.md), [environment appendix](docs/reference/environment-and-posix-appendix.md), [Handbook — Chapter 4](handbook/04-the-booter-runtime.md).
## Kernel image and Pear seeder parity
The canonical tree is **`kernel/`**; **`packages/bare-os-seeder/kernel/`** must stay **byte-identical** for Pear staging. After editing **`kernel/`** (or when **`verify-kernel-seeder-parity`** fails):
Canonical tree: **`kernel/`**; **`packages/bare-os-seeder/kernel/`** must stay **byte-identical**.
- **Full maintainer rebuild** (coreutils, bare-libs, init bundle, extensions index, parity): **`npm run maintainer:kernel-image`** from the repo root.
- **Sync only** (requires prior correct **`kernel/`**): **`npm run maintainer:sync-kernel-seeder`** — runs **`rsync -a --delete kernel/ packages/bare-os-seeder/kernel/`** then **`verify-kernel-seeder-parity`**. To re-bundle **`/boot/init.js`** first: **`npm run maintainer:sync-kernel-seeder:bundle`**.
- **Full maintainer rebuild:** **`npm run maintainer:kernel-image`**
- **Sync only:** **`npm run maintainer:sync-kernel-seeder`** (or **`…:bundle`** to re-bundle **`/boot/init.js`** first)
Equivalent manual steps are documented in [handbook ch.7](handbook/07-operations-and-development.md).
Details: [Handbook — Chapter 7](handbook/07-operations-and-development.md).
## Contributing / CI
Root **`npm test`** runs **`scripts/verify-kernel-seeder-parity.mjs`**, **`scripts/verify-pear-no-static-node-import.mjs`** (no bare **`fs`**/**`path`** imports in booter/seeder sources), and **`scripts/verify-ctx-api-feature-bits.mjs`** (after workspace builds) so **`kernel/`** stays mirrored in the seeder package and **`bareOsCtxApiVersion`** stays aligned with advertised kernel feature bits. See [scripts/README.md](scripts/README.md).
Root **`npm test`** runs workspace tests plus **`pretest`** hooks (kernel/seeder parity, **`verify-ctx-api-feature-bits`**, Pear import policy, doc link and contract checks). Maintainer script inventory: [scripts/README.md](scripts/README.md).
Before a release tag, run **`npm run release-checklist`** ([`scripts/release-checklist.mjs`](scripts/release-checklist.mjs)) — see [docs/release-checklist.md](docs/release-checklist.md).
## Observability (host env)
Optional guest paths **`BARE_OS_TELEMETRY_NDJSON`** and **`BARE_OS_TELEMETRY_OTEL_JSONL`** append capped JSON lines for boot and var-log mirrors (**`lifecycleSchemaVersion` / `telemetrySchemaVersion` 3**). Coalesced session metrics are available at **`/proc/bare_os/metrics_live.json`** (poll interval **`BARE_OS_PROC_POLL_MS`**). Dev-only **`BARE_OS_DIAGNOSTICS_SUBSCRIBE=1`** enables **`ctx.bareOsDiagnosticsSubscribe`** for structured booter diagnostics. Details: [kernel extensions](docs/reference/kernel-extensions.md), [environment appendix](docs/reference/environment-and-posix-appendix.md), [JSON Schemas](docs/schemas/).
Optional guest paths **`BARE_OS_TELEMETRY_NDJSON`** and **`BARE_OS_TELEMETRY_OTEL_JSONL`** append capped JSON lines; records carry **`lifecycleSchemaVersion`** and **`telemetrySchemaVersion`** aligned with stock **`BARE_OS_LIFECYCLE_SCHEMA_VERSION`** (see [compatibility matrix](docs/reference/compatibility-matrix.md) and [environment appendix](docs/reference/environment-and-posix-appendix.md)). Coalesced metrics: **`/proc/bare_os/metrics_live.json`** (poll **`BARE_OS_PROC_POLL_MS`**). Dev-only **`BARE_OS_DIAGNOSTICS_SUBSCRIBE=1`** enables **`ctx.bareOsDiagnosticsSubscribe`**. [Kernel extensions](docs/reference/kernel-extensions.md) · [JSON Schemas](docs/schemas/).
## License
developer-guide/02-the-context-object.md
+1 -1
View File
@@ -95,7 +95,7 @@ The following are set on `ctx` before the kernel starts (unless noted as overwri
- **`bareOsApplyTheme()`** / **`bareOsListThemes()`** — Re-apply **`BARE_OS_THEME`** / **`LS_COLORS`** / **`BARE_OS_DIRCOLORS`** to **`vfs.env`** (including **`BARE_OS_COLOR_DEPTH`** downgrades for **`BARE_OS_COLOR_*`**). Used by **`/bin/theme`** and documented for custom tooling (see [`bare-os-theme-presets.js`](../packages/bare-os-booter/lib/bare-os-theme-presets.js)).
- **`runBinCommand(argv)`** — Runs a command with the **same** resolution rules as the interactive shell (used by **`time`**, **`xargs`**, and similar)
- **`registerKernelShutdownHook(fn)`** — Register an async or sync function to run when the REPL session ends, **before** **`stopBareInitd`** and initd **disposers**. Pair with **`registerBareInitdDisposer(fn)`** in [`bare-initd.js`](../packages/bare-os-booter/lib/bare-initd.js) when you need teardown **after** shutdown hooks but still inside **`stopBareInitd`** (intervals, sync cleanup).
- **`bareOsSubscribeBootEvent(fn)`** / **`bareOsEmitBootEvent(ev)`** — Subscribe to or emit structured boot lifecycle events (same shape as **`BARE_OS_BOOT_TRACE=ndjson`** records). Phase records carry **`lifecycleSchemaVersion: 3`** alongside **`telemetrySchemaVersion`** where applicable (see [kernel extensions](../docs/reference/kernel-extensions.md)).
- **`bareOsSubscribeBootEvent(fn)`** / **`bareOsEmitBootEvent(ev)`** — Subscribe to or emit structured boot lifecycle events (same shape as **`BARE_OS_BOOT_TRACE=ndjson`** records). Phase records carry **`lifecycleSchemaVersion`** and **`telemetrySchemaVersion`** set from stock **`BARE_OS_LIFECYCLE_SCHEMA_VERSION`** (see [compatibility matrix](../docs/reference/compatibility-matrix.md) and [kernel extensions](../docs/reference/kernel-extensions.md)).
- **`bareOsSubscribeKernelEvent(fn)`** / **`bareOsEmitKernelEvent(ev)`** — Namespaced kernel event bus (e.g. **`topic: 'boot.phase'`**, **`bootStage`**); also mirrored to diagnostics subscribers with **`source: 'kernel'`**.
- **`bareOsAcquireKeyHandle(hint?)`** — Key-broker sketch returning an **opaque** handle string (no raw key material in guest).
- **`bareOsSubscribeHdmsLifecycle(fn)`** — After HDMS **`activate`** / before **`deactivate`**, run callbacks with **`{ kind, labels? }`**.
developer-guide/README.md
+17
View File
@@ -25,6 +25,7 @@ This project is **experimental research software**. APIs described here follow t
## On this page
- [Who this is for](#who-this-is-for)
- [Maintainer cheat sheet](#maintainer-cheat-sheet-artifacts--verifiers)
- [Reading order](#reading-order)
- [Related docs](#related-docs)
@@ -39,6 +40,22 @@ This project is **experimental research software**. APIs described here follow t
---
## Maintainer cheat sheet (artifacts → verifiers)
| What you touch | Responsibility | Root check |
| --- | --- | --- |
| [`packages/bare-os-coreutils/lib/commands.mjs`](../packages/bare-os-coreutils/lib/commands.mjs) | Tier-1 `/bin` names, `man.json` coverage | `verify-man-coverage.mjs`, `verify-doc-tier1-count.mjs` (via **`pretest`**) |
| [`packages/bare-os-coreutils/build.mjs`](../packages/bare-os-coreutils/build.mjs) | Emit `kernel/bin/*`, man merge | `npm run build -w bare-os-coreutils` |
| [`kernel/lib/boot/`](../kernel/lib/boot/), [`kernel/lib/init/`](../kernel/lib/init/) | Init bundle sources | `bundle-kernel-init.mjs`, `verify-init-bundle-recipe.mjs` |
| [`kernel/`](../kernel/) vs [`packages/bare-os-seeder/kernel/`](../packages/bare-os-seeder/kernel/) | Byte-identical mirror | `verify-kernel-seeder-parity.mjs` |
| [`packages/bare-os-booter/lib/bare-os-ctx-api.js`](../packages/bare-os-booter/lib/bare-os-ctx-api.js) | **`BARE_OS_CTX_API_VERSION`** | `verify-ctx-api-feature-bits.mjs`, `verify-compat-matrix.mjs`, `gen-ctx-client-helper.mjs` |
| [`docs/reference/compatibility-matrix.md`](../docs/reference/compatibility-matrix.md) | Version table for releases | `verify-compat-matrix.mjs`, `verify-doc-contracts.mjs` |
| [`docs/reference/posix-compliance-matrix.json`](../docs/reference/posix-compliance-matrix.json) | POSIX profile linkage | `verify-posix-compliance-matrix.mjs`, `gen-posix-dashboard.mjs` |
Full script index: [scripts/README.md](../scripts/README.md). Gate everything with **`npm run pretest`** before pushing doc or contract edits.
---
## Reading order
- **[01 — Two runtimes: host vs in-image](01-two-runtimes-host-vs-image.md)** — Pear/Node packages vs Hyperdrive JS evaluated with `AsyncFunction`; trust boundaries.
docs/CONTRIBUTING-DOCS.md
+57 -1
View File
@@ -8,6 +8,7 @@ This repository ships documentation as **GitHub-flavored Markdown** (no static s
| Audience | Tree | Role |
| --- | --- | --- |
| Short evergreen explainers | [docs/concepts/](concepts/README.md) | Two drives, boot, P2P, identity, POSIX — link out to handbook + reference |
| Operators / first run | [users-manual/](../users-manual/README.md) | Step-by-step: install, seeder/booter, shell, identity, troubleshooting |
| Narrative / architecture | [handbook/](../handbook/README.md) | Why the system is shaped this way; trust, protocol, runtime |
| Extenders / contributors | [developer-guide/](../developer-guide/README.md) | `ctx`, `/bin`, Pear, testing, security |
@@ -37,6 +38,59 @@ Use a consistent blockquote pattern so callouts render clearly on GitHub:
Keep the **bold label** on the first line, then a line break, then the body.
### GitHub-style alerts (optional)
On hosts that render [GitHub-flavored alerts](https://github.blog/changelog/2022-02-10-add-markdown-support-for-alerts/), you may use:
```markdown
> [!NOTE]
> Supplementary context.
> [!TIP]
> A shortcut or workflow.
> [!IMPORTANT]
> Non-obvious requirement.
> [!WARNING]
> Risk of data loss or security impact.
> [!CAUTION]
> Experimental or high-impact action.
```
**Forge fallback:** some Git forges (including some self-hosted UIs) show these as plain blockquotes. When in doubt, keep the **blockquote + bold label** form above as the portable baseline, or duplicate the critical sentence in both styles only on entry pages (root `README.md`, `docs/README.md`).
---
## Collapsible sections (`<details>`)
Use HTML **`<details><summary>…</summary>…</details>`** to hide long protocol tables, copy-paste dumps, or secondary feature lists. Prefer summaries under ~120 characters. Do not put essential safety warnings **only** inside a collapsed block.
---
## Footnotes
Use reference-style footnotes sparingly for acronyms or citations in the handbook:
```markdown
Hyperdrive replication uses Merkle proofs[^hc].
[^hc]: See Hypercore / Hyperdrive project docs linked from the handbook.
```
---
## Badges
Root `README.md` may use **license** and **Node engines** shields. Avoid badge clutter elsewhere unless a package README benefits from a single status line.
---
## Task lists in canonical docs
Avoid GitHub **`- [ ]` task lists** in normative documentation (they read as unfinished product). Use tasks in **issues/PRs** or explicit numbered steps instead.
---
## Mermaid diagrams
@@ -49,12 +103,14 @@ Keep the **bold label** on the first line, then a line break, then the body.
If a diagram would need pixel-perfect branding or screenshots, add a **placeholder image** under [docs/images/](images/README.md) and reference it from the relevant page.
**Preview:** there is no Mermaid linter in **`pretest`**; use your editor or a Mermaid preview before pushing complex diagrams.
---
## Links and paths
- Use **relative** `.md` links between docs so [scripts/verify-doc-links.mjs](../scripts/verify-doc-links.mjs) can resolve targets.
- The link checker walks `docs/`, `handbook/`, `developer-guide/`, `users-manual/`, `scripts/`, `packages/`, `kernel/`, plus root `README.md` and `DOCUMENTATION.md` (and any `.md` under those trees, including `docs/PEAR-RUN.md`).
- The link checker walks `docs/` (including **`docs/concepts/*.md`**), `handbook/`, `developer-guide/`, `users-manual/`, `scripts/`, `packages/`, `kernel/`, plus root `README.md` and `DOCUMENTATION.md` (and any `.md` under those trees, including `docs/PEAR-RUN.md`).
- **`packages/bare-os-seeder/kernel/**`** is skipped (mirror of `kernel/`); fix links in **`kernel/**`** only.
---
docs/README.md
+75 -1
View File
@@ -5,9 +5,32 @@
> **Important**
> This project is **research software**, not a production operating system. Trust boundaries, security limits, and stability expectations are spelled out in the [handbook preface](../handbook/00-preface.md).
Evergreen explainers (two drives, boot, swarm, identity, POSIX): **[Concepts](concepts/README.md)**.
## On this page
- [Pick your depth](#pick-your-depth)
- [Architecture snapshot](#architecture-snapshot)
- [Two-drive and swarm path](#two-drive-and-swarm-path)
- [POSIX + P2P reading order](#posix--p2p-reading-order)
- [Contract spine](#contract-spine-quick-cross-links)
- [POSIX + P2P consolidated dashboard](#posix--p2p-consolidated-dashboard)
- [Documentation map](#documentation-map)
- [Topic index](#topic-index-canonical-reference-per-subject)
- [Contract bump checklist](#contract-bump-checklist)
## Pick your depth
| Time | Goal | Path |
| --- | --- | --- |
| **5 min** | See it run | [User manual — ch.3](../users-manual/03-running-seeder-and-booter.md) |
| **30 min** | Two drives + P2P boot | [Concepts](concepts/README.md) → [Handbook ch.3](../handbook/03-protocol-and-disk.md) |
| **2 h** | Extend `/bin` or kernel | [Developer guide §1–6](../developer-guide/01-two-runtimes-host-vs-image.md) + [KERNEL_CONTRACT](architecture/KERNEL_CONTRACT.md) |
| **Release** | Avoid CI surprises | [scripts/README.md](../scripts/README.md) + [Release checklist](release-checklist.md) |
## Architecture snapshot
End-to-end data path from swarm connection to guest syscalls (canonical overview; details in the [handbook](../handbook/README.md) and [kernel contract](architecture/KERNEL_CONTRACT.md)):
End-to-end data path from swarm connection to guest syscalls (canonical overview; details in the [handbook](../handbook/README.md), [concepts — P2P](concepts/p2p-swarm-and-protomux.md), and [kernel contract](architecture/KERNEL_CONTRACT.md)):
```mermaid
flowchart TB
@@ -34,6 +57,56 @@ flowchart TB
BIN --> CTX
```
## Two-drive and swarm path
How the **personal** drive sits beside the **system** image and how the booter reaches both after swarm replication (narrative: [concepts — Two drives](concepts/two-drive-model.md), [concepts — Boot](concepts/boot-and-init-timeline.md)):
```mermaid
flowchart TB
subgraph p2p [Swarm]
T[Hyperswarm topic]
M[Protomux bare-os-v1]
end
subgraph booter [Booter host]
SD[SwarmDisk Corestore]
VFS[VFS router]
end
subgraph drives [Hyperdrives]
SYS[System drive read policy]
PER[Personal drive home and .bare]
end
T --> M
M --> SD
SD --> SYS
SD --> PER
SYS --> VFS
PER --> VFS
VFS --> SH[Shell and /bin]
```
## POSIX + P2P reading order
Read **once** in this order when you need the full contract picture; then use the [consolidated dashboard](#posix--p2p-consolidated-dashboard) as your bookmark.
| Step | Focus | Human doc | Machine / generated |
| --- | --- | --- | --- |
| 1 | Declared stance | [POSIX declared profile](architecture/POSIX_DECLARED_PROFILE.md) | [`posix-compliance-matrix.json`](reference/posix-compliance-matrix.json) |
| 2 | Dashboard | [POSIX compliance dashboard](reference/posix-dashboard.md) | `pretest` → `gen-posix-dashboard.mjs` |
| 3 | Utilities + shell | [Handbook ch.9](../handbook/09-posix-utilities-shell-and-vfs.md) | [`syscalls.example.json`](../kernel/etc/bare-os/syscalls.example.json) |
| 4 | Syscall facade | [POSIX syscall facade map](reference/posix-syscall-facade-map.md) | [`bare-os-syscalls.schema.json`](schemas/bare-os-syscalls.schema.json) |
| 5 | P2P vs POSIX boundary | [Handbook ch.12](../handbook/12-p2p-stack-and-posix-boundaries.md) | [Capability words](reference/capability-words.md) |
**Environment variables** (full inventory, do not duplicate in prose): [Environment and POSIX appendix](reference/environment-and-posix-appendix.md).
### Compared at a glance
| | Bare OS | Classic OS image | Container on a host |
| --- | --- | --- | --- |
| **Distribution** | P2P Hyperdrive + swarm | ISO / image mirror | Registry pull |
| **Mutable user state** | Personal Hyperdrive | Local disk | Writable layers / volumes |
| **Guest execution** | `ctx` + VFS over drives | Kernel + real HW/VM | Namespaces + host kernel |
| **POSIX** | Declared profile + facade | Full kernel | Often libc + syscall pass-through |
---
## Contract spine (quick cross-links)
@@ -90,6 +163,7 @@ Details: [scripts/README.md](../scripts/README.md) (maintainer build order), [de
| I want to… | Start here |
| --- | --- |
| **Orient** quickly (two drives, boot, P2P, POSIX) | [Concepts](concepts/README.md) |
| **Run** the seeder and booter and use the shell | [User manual](../users-manual/README.md) |
| **Understand** architecture, protocol, and design intent | [Handbook](../handbook/README.md) |
| **Extend** `/bin`, scripts, Pear apps, or `ctx` | [Developer guide](../developer-guide/README.md) |
docs/audit/bundle-health.json
+1 -1
View File
@@ -1,6 +1,6 @@
{
"schemaVersion": 1,
"generatedAt": "2026-04-06T03:20:32.248Z",
"generatedAt": "2026-04-06T10:31:01.458Z",
"normativeManifest": "packages/bare-os-booter/lib/bare-module-manifest.json",
"buildTool": "packages/bare-os-bare-libs/build.mjs",
"bundles": [
docs/concepts/README.md
+22
View File
@@ -0,0 +1,22 @@
# Concepts — evergreen explainers
These pages are **short, stable introductions** to how Bare OS fits together. They intentionally **link outward** to the handbook (narrative depth) and `docs/reference` (normative numbers and APIs) instead of duplicating them.
> **Tip**
> New to the repo? Read **[Two-drive model](two-drive-model.md)** then **[Boot and init timeline](boot-and-init-timeline.md)**, then run the [user manual — ch.3](../../users-manual/03-running-seeder-and-booter.md).
## Pages
| Topic | Summary |
| --- | --- |
| [Two-drive model](two-drive-model.md) | System vs personal Hyperdrive, `$HOME`, `/.bare`, VFS routing |
| [Boot and init timeline](boot-and-init-timeline.md) | Seeder → swarm → booter → `/boot/init.js` → shell |
| [P2P swarm and Protomux](p2p-swarm-and-protomux.md) | Topic, channel `bare-os-v1`, MBR, replication sketch |
| [Identity and vault](identity-and-vault.md) | Guest vs logged-in, Ed25519 account, vault snapshots |
| [POSIX stance](posix-stance.md) | Declared profile, what “POSIX-like” means here, where to look |
## Where to go next
- **Documentation hub** — [docs/README.md](../README.md) (full map, curricula, POSIX dashboard).
- **Handbook** — [handbook/README.md](../../handbook/README.md).
- **Developer guide** — [developer-guide/README.md](../../developer-guide/README.md).
docs/concepts/boot-and-init-timeline.md
+32
View File
@@ -0,0 +1,32 @@
# Concept — Boot and init timeline
This is the **happy-path** boot story at a glance. Wire formats and failure modes are in the handbook and protocol reference.
```mermaid
sequenceDiagram
participant Seeder as Seeder
participant Topic as HyperswarmTopic
participant Booter as Booter
participant Sys as SystemHyperdrive
participant Per as PersonalHyperdrive
participant Init as boot_init_js
Seeder->>Topic: publish MBR and blocks
Booter->>Topic: discover peers replicate
Booter->>Sys: open using MBR key material
Booter->>Per: open or create personal drive
Booter->>Init: run start(ctx)
Init->>Booter: guest syscalls via ctx and VFS
```
## Roles
1. **Seeder** — stages `kernel/` into the system drive, writes the **512-byte MBR**, stays online so others can replicate.
2. **Booter** — joins the same swarm topic, opens **system + personal** drives, constructs **`ctx`**, executes **`/boot/init.js`**.
3. **Stock kernel (`/boot/init.js`)** — brings up initd/cron themes, shell, and guest-visible policy as documented in the kernel contract.
## Read next
- **Handbook** — [Chapter 3 — Protocol and disk](../../handbook/03-protocol-and-disk.md) (includes sequence diagram and MBR layout details).
- **Handbook** — [Chapter 4 — Booter runtime](../../handbook/04-the-booter-runtime.md).
- **Reference** — [KERNEL_CONTRACT.md](../architecture/KERNEL_CONTRACT.md).
- **P2P detail** — [P2P swarm and Protomux](p2p-swarm-and-protomux.md).
docs/concepts/identity-and-vault.md
+33
View File
@@ -0,0 +1,33 @@
# Concept — Identity and vault
Bare OS carries **per-user cryptographic identity** on the **personal** drive. Out of the box you are usually in a **guest** session until you **`login`**.
```mermaid
flowchart TB
subgraph session [Session modes]
G[Guest default]
U[Unlocked user]
end
subgraph actions [Common commands]
L[login]
O[logout]
S[savevault]
end
G -->|L| U
U -->|O optional savevault| G
U --> S
```
- **Guest** — safe default; restricted visibility into **`/.bare`** (policy-dependent).
- **Unlocked** — registered/logged-in user with Ed25519-backed account material on the personal drive.
- **Vault** — encrypted snapshot workflow via **`savevault`** / **`logout --save`** (see user manual and coreutils `man` entries).
> **Warning**
> Treat vault and identity material like **secrets at rest in your threat model**. Read the vault threat model before relying on this software for sensitive data.
## Read next
- **User manual** — [Chapter 5 — Home, identity, vault](../../users-manual/05-home-identity-and-vault.md).
- **Handbook** — [Chapter 5 — Identity, vault, HDMS](../../handbook/05-identity-vault-and-hdms.md).
- **Security** — [Vault threat model](../security/vault-threat-model.md).
- **Reference** — [package-bare-os-booter.md](../reference/package-bare-os-booter.md) (guest `/.bare` policy, env vars).
docs/concepts/p2p-swarm-and-protomux.md
+26
View File
@@ -0,0 +1,26 @@
# Concept — P2P swarm and Protomux
Bare OS distributes the **system image** over the same kind of stack Holepunch tooling uses: **Hyperswarm** for peer discovery, **Protomux** for typed channels on the encrypted stream.
## Names you will see
- **Swarm topic** — derived from the string **`bare-os-v1`** (see protocol package exports).
- **Protomux channel** — **`bare-os-v1`** carries replication and seed RPCs used during boot.
- **MBR block** — 512 bytes, **`BIOS`** magic, Hyperdrive **key material** at fixed offsets so a booter can open the system drive without a central registry.
## Sketch
```mermaid
flowchart LR
A[Peer A seeder] --> T[Topic bare-os-v1]
B[Peer B booter] --> T
T --> M[Protomux channels]
M --> D[Hyperdrive replication]
```
## Read next
- **Handbook** — [Chapter 3 — Protocol and disk](../../handbook/03-protocol-and-disk.md).
- **Handbook** — [Chapter 12 — P2P stack vs POSIX](../../handbook/12-p2p-stack-and-posix-boundaries.md).
- **Reference** — [package-bare-os-protocol.md](../reference/package-bare-os-protocol.md).
- **Booter teardown** — [hyperswarm-protomux-teardown.md](../reference/hyperswarm-protomux-teardown.md).
docs/concepts/posix-stance.md
+23
View File
@@ -0,0 +1,23 @@
# Concept — POSIX stance
Bare OS exposes a **POSIX-shaped** shell, **`/bin`**, and VFS, but it is **not** a certified UNIX kernel. The project publishes a **declared profile** so you know what is promised vs out of scope.
## What “POSIX-like” means here
- **Tier-1 `/bin`** — a curated set of utilities built from [bare-os-coreutils](../../packages/bare-os-coreutils/README.md); names and behavior are tracked against a declared profile and Issue 7 traceability docs.
- **Syscalls** — many operations go through **`ctx.bareOsSyscall`** and **`/proc`** JSON mirrors rather than a hardware trap interface — see the syscall facade map.
- **Sockets** — optional **socket FD bridge** behind env gates; not “Linux identical.”
## Where the contract lives
| Artifact | Role |
| --- | --- |
| [POSIX declared profile](../architecture/POSIX_DECLARED_PROFILE.md) | Narrative stance, non-goals |
| [POSIX compliance dashboard](../reference/posix-dashboard.md) | Generated summary |
| [POSIX Issue 7 traceability](../reference/posix-issue7-traceability.md) | XBD/XSH/XCU mapping |
| [Compatibility matrix](../reference/compatibility-matrix.md) | Profile version, ctx API, schemas |
## Read next
- **Handbook** — [Chapter 9 — POSIX, shell, VFS](../../handbook/09-posix-utilities-shell-and-vfs.md).
- **Reference** — [posix-syscall-facade-map.md](../reference/posix-syscall-facade-map.md) · [syscall-socket-contract.md](../reference/syscall-socket-contract.md).
docs/concepts/two-drive-model.md
+38
View File
@@ -0,0 +1,38 @@
# Concept — Two-drive model
Bare OS splits the world into two **Hyperdrives** so you can **replicate the OS image** without forking everyone’s private state.
## System drive
- Holds the **stock tree**: `/boot`, `/bin`, kernel bundles, `man` JSON, optional `/lib/bare` bundles.
- Treated as **image policy** — you replicate it from peers like a read-mostly artifact.
## Personal drive
- Holds **per-machine mutable state**: your **`$HOME`**, **`/.bare`** (identity, policy blobs guests may not see), history, and anything that should not be overwritten when the system image updates.
## VFS routing (mental model)
The booter-backed VFS **mounts both** and **routes paths**: home and personal namespaces land on the personal drive; the rest of the POSIX-shaped tree comes from the system image. Exact policy and edge cases live in the booter reference and handbook.
```mermaid
flowchart LR
subgraph routes [Path classes]
H["$HOME and under"]
B["/.bare"]
R["Rest of tree e.g. /bin /boot"]
end
subgraph drives [Drives]
P[Personal Hyperdrive]
S[System Hyperdrive]
end
H --> P
B --> P
R --> S
```
## Read next
- **Handbook** — [Chapter 5 — Identity, vault, HDMS](../../handbook/05-identity-vault-and-hdms.md) (how `/.bare` behaves for guests vs users).
- **Reference** — [package-bare-os-booter.md](../reference/package-bare-os-booter.md) (VFS, guest `/.bare` policy, env gates).
- **Security** — [Vault threat model](../security/vault-threat-model.md).
docs/reference/repo-layout-and-root.md
+6
View File
@@ -22,6 +22,7 @@ bare-operating-system/
│ ├── README.md # Index + reading order
│ ├── 01-two-runtimes-host-vs-image.md … 12-bare-modules-and-pear-ecosystem.md
├── LICENSE # Apache-2.0 notice (root repo)
├── patches/ # patch-package deltas (applied post-install; see § patches below)
├── .gitignore # Ignore rules
├── .prettierrc # Prettier formatting defaults
├── .github/
@@ -154,3 +155,8 @@ JSON: `semi: false`, `singleQuote: true`, `trailingComma: "none"`.
- **Triggers**: `push` and `pull_request` to `main`.
- **Job `test`**: `ubuntu-latest`, checkout, `actions/setup-node@v4` with Node 20 and npm cache on `package-lock.json`, then `npm ci`, **`npm install -g bare`** (for `brittle-bare` / `test.identity.js`), and `npm test`.
---
## 9. Root: `patches/` ([patch-package](https://github.com/ds300/patch-package))
The repo may ship **`patches/*.patch`** files in **patch-package** format (for example [`patches/autopass+3.4.0.patch`](../../patches/autopass+3.4.0.patch)) so maintainers can apply small **upstream dependency fixes** during development. They are **not** staged into the guest Hyperdrive. **`patch-package`** is a root devDependency; wire a **`postinstall`** script if you want patches applied automatically after **`npm ci`**. Document **why** each patch exists in the commit message and keep diffs minimal.
handbook/00-preface.md
+7
View File
@@ -14,6 +14,12 @@ This preface states the thesis in plain language, places the project next to fam
Bare OS is a **Unix-flavored environment** whose **system root** lives on a **Hyperdrive** keyed from a tiny **512-byte MBR** you read from peers. A **seeder** application publishes that drive; a **booter** application finds peers on a fixed **Hyperswarm** topic, replicates the drive, mounts a **separate personal Hyperdrive** for mutable state, and runs a JavaScript **kernel** (`/boot/init.js`) and a **Tier-1 `/bin`** built from small **`AsyncFunction`** scripts. Execution is **one host process** (Pear or Node) simulating POSIX paths, a line shell, and synthetic `/proc`-style views—not a hardware kernel.
### A deliberately leaky analogy
Picture the **system drive** as a **read-only live image** many peers can help you replicate, and the **personal drive** as **your private stick** for home, identity, and vault data—except both are **Hyperdrives** and the “CPU” is still **one Pear/Node process** interpreting scripts. That image helps you **orient**; it is **not** a security promise. You still choose **which peers** to trust, and anything in **`/bin`** can reach whatever the host runtime allows. Short evergreen pages: [docs/concepts — Two-drive model](../docs/concepts/two-drive-model.md).
**Non-goal:** “P2P” does **not** mean you can skip thinking about **trust, backups, and passphrase quality**.
```mermaid
flowchart LR
subgraph p2p[P2P]
@@ -36,6 +42,7 @@ flowchart LR
## On this page
- [The thesis in one paragraph](#the-thesis-in-one-paragraph)
- [A deliberately leaky analogy](#a-deliberately-leaky-analogy)
- [How this handbook relates to other docs](#how-this-handbook-relates-to-other-docs)
- [Comparison frame](#comparison-frame-not-marketing)
- [Security and limits](#security-and-limits)
handbook/02-blueprints.md
+6 -2
View File
@@ -77,17 +77,21 @@ flowchart LR
## 2. Two drives on the booter
The VFS **merges** both drives into one POSIX-shaped tree. Typical **personal** prefixes include **`$HOME`**, **`/tmp`**, **`/var/log`**, and **`/.bare/**`; most of **`/bin`**, **`/boot`**, **`/etc`**, **`/lib`**, … resolve on the **system** image. Exact routing is policy-sensitive—see the booter reference for guest **`/.bare`** visibility rules.
```mermaid
flowchart TB
subgraph booterProcess [Booter process]
VFS[VFS layer]
Sys[System Hyperdrive]
Pers[Personal Hyperdrive]
VFS -->|"paths outside HOME"| Sys
VFS -->|"HOME and below"| Pers
VFS -->|"bin boot etc lib"| Sys
VFS -->|"HOME tmp var log .bare"| Pers
end
```
Evergreen diagram: [docs/concepts — Two-drive model](../docs/concepts/two-drive-model.md).
**Trust model (pragmatic):**
- **System drive** content is **whatever replicated from the swarm** matching the MBR keys. In dev you treat the seeder as trusted; in the wild this is “who you peer with.”
handbook/03-protocol-and-disk.md
+20
View File
@@ -98,6 +98,26 @@ When the host sets **`BARE_OS_VFS_SYSTEM_RO_ALIAS`** to an absolute path (for ex
There is **intentionally** no “use my checkout’s `kernel/` if the network fails” path—the project forces you to think about **availability** of the swarm.
### End-to-end boot sequence (MBR to `start(ctx)`)
This view complements the **seeder ↔ wire** sketch above by naming **both drives** and **`/boot/init.js`**. Same story as [docs/concepts — Boot timeline](../docs/concepts/boot-and-init-timeline.md).
```mermaid
sequenceDiagram
participant Seeder as Seeder
participant Topic as HyperswarmTopic
participant Booter as Booter
participant Sys as SystemHyperdrive
participant Per as PersonalHyperdrive
participant Init as boot_init_js
Seeder->>Topic: publish MBR and blocks
Booter->>Topic: discover peers replicate
Booter->>Sys: open using MBR key material
Booter->>Per: open or create personal drive
Booter->>Init: execute start(ctx)
Init->>Booter: guest syscalls via ctx and VFS
```
---
## Message IDs — what each is for
handbook/05-identity-vault-and-hdms.md
+16
View File
@@ -14,6 +14,22 @@ This chapter covers **who the session is** (guest vs unlocked), **where keys liv
4. **`hdms create` / `hdms add`** — Writable or read-only drives appear under **`/mnt/<label>`**; the registry JSON on the personal drive is the source of truth.
5. **`logout`** — Sensitive material is zeroed; you return to **guest**. **`logout --save`** or **`savevault`** can snapshot selected paths into **`/.bare/vault/`** as encrypted records.
```mermaid
flowchart TB
G[Guest boot defaults]
L[login / login --new]
U[Unlocked session HOME and HDMS]
SV[savevault or logout --save]
LO[logout to guest]
G --> L
L --> U
U --> SV
U --> LO
LO --> G
```
Operator trust framing: [Vault threat model](../docs/security/vault-threat-model.md).
**Pairing hints (operators):** when the host sets **`BARE_OS_AUTOPASS_INVITE_URL`**, the guest exposes a JSON hint at **`/proc/bare_os/hdms_hints.json`**. The guest does **not** open network URLs automatically; hosts or operators consume the hint out-of-band. **`/proc/bare_os/hdms_health.json`** (and flat alias) summarizes **non-secret** mount/registry metadata (counts, labels) for dashboards—no key material.
**Unlock errors (automation):** when **`unlockIdentity`** in [`identity-session.js`](../packages/bare-os-booter/lib/identity-session.js) throws, stable **`Error.code`** values include **`BARE_OS_IDENTITY_NO_ACCOUNT`** (no **`/.bare/account`** blob) and **`BARE_OS_IDENTITY_PASSPHRASE_REJECTED`** (decrypt/parse failure; **`error.cause`** carries the underlying error when present). Human-readable messages remain for interactive **`login`**.
handbook/README.md
+1 -1
View File
@@ -18,7 +18,7 @@ This project is **experimental research software**, not a production OS. It is l
## How this handbook fits the repo
**[Documentation home](../docs/README.md)** — Single map of every tree: user manual, this handbook, developer guide, reference, **[glossary](../docs/glossary.md)**, **[FAQ](../docs/faq.md)**, **[troubleshooting router](../docs/troubleshooting.md)**, **[contributing to docs](../docs/CONTRIBUTING-DOCS.md)**.
**[Documentation home](../docs/README.md)** — Single map of every tree: user manual, this handbook, developer guide, reference, **[concepts (evergreen)](../docs/concepts/README.md)**, **[glossary](../docs/glossary.md)**, **[FAQ](../docs/faq.md)**, **[troubleshooting router](../docs/troubleshooting.md)**, **[contributing to docs](../docs/CONTRIBUTING-DOCS.md)**.
**[Preface — why Bare OS](00-preface.md)** — Thesis, comparison to classic images, security limits, outlook, contributor paths.
kernel/README.md
+1 -1
View File
@@ -4,7 +4,7 @@ Files in this directory are **read from disk by the seeder** (or copied into `pa
**This `README.md` file** only documents the tree layout in the repository; the seeder **does not** install it as **`/README.md`** on the image (so the guest root directory stays free of repo docs).
**Documentation:** [User manual](../users-manual/README.md) · [Handbook](../handbook/README.md) · [Kernel image reference](../docs/reference/kernel-image.md) · [Developer guide](../developer-guide/README.md).
**Documentation:** [Concepts — Boot](../docs/concepts/boot-and-init-timeline.md) · [User manual](../users-manual/README.md) · [Handbook](../handbook/README.md) · [Kernel image reference](../docs/reference/kernel-image.md) · [Developer guide](../developer-guide/README.md).
## Staging map (seeder)
kernel/etc/bare-os/posix_utilities.json
+1 -1
View File
@@ -1,7 +1,7 @@
{
"schema": 2,
"profileId": "bare-os-posix-like",
"generatedAt": "2026-04-06T03:20:31.090Z",
"generatedAt": "2026-04-06T10:31:00.374Z",
"note": "Sparse POSIX Issue 7 coverage hints for /bin utilities. Omitted command names are not yet profiled here.",
"commandIndex": [
{
kernel/lib/bare/manifest.json
+260 -260
View File
@@ -25,12 +25,6 @@
"compactEncoding"
]
},
{
"path": "/lib/bare/bundles/protomux.js",
"keys": [
"protomux"
]
},
{
"path": "/lib/bare/bundles/bareUrl.js",
"keys": [
@@ -49,6 +43,12 @@
"bareEncoding"
]
},
{
"path": "/lib/bare/bundles/protomux.js",
"keys": [
"protomux"
]
},
{
"path": "/lib/bare/bundles/bareEvents.js",
"keys": [
@@ -68,15 +68,9 @@
]
},
{
"path": "/lib/bare/bundles/bareCrypto.js",
"path": "/lib/bare/bundles/bareAnsiEscapes.js",
"keys": [
"bareCrypto"
]
},
{
"path": "/lib/bare/bundles/bareReadline.js",
"keys": [
"bareReadline"
"bareAnsiEscapes"
]
},
{
@@ -86,27 +80,15 @@
]
},
{
"path": "/lib/bare/bundles/fetch.js",
"path": "/lib/bare/bundles/bareReadline.js",
"keys": [
"fetch"
"bareReadline"
]
},
{
"path": "/lib/bare/bundles/bareAnsiEscapes.js",
"path": "/lib/bare/bundles/bareCrypto.js",
"keys": [
"bareAnsiEscapes"
]
},
{
"path": "/lib/bare/bundles/bareAsyncHooks.js",
"keys": [
"bareAsyncHooks"
]
},
{
"path": "/lib/bare/bundles/bareAssert.js",
"keys": [
"bareAssert"
"bareCrypto"
]
},
{
@@ -121,6 +103,12 @@
"bareAppKit"
]
},
{
"path": "/lib/bare/bundles/bareAsyncHooks.js",
"keys": [
"bareAsyncHooks"
]
},
{
"path": "/lib/bare/bundles/bareAtomics.js",
"keys": [
@@ -128,9 +116,9 @@
]
},
{
"path": "/lib/bare/bundles/bareBuffer.js",
"path": "/lib/bare/bundles/bareAssert.js",
"keys": [
"bareBuffer"
"bareAssert"
]
},
{
@@ -140,15 +128,15 @@
]
},
{
"path": "/lib/bare/bundles/bareBundleCompile.js",
"path": "/lib/bare/bundles/fetch.js",
"keys": [
"bareBundleCompile"
"fetch"
]
},
{
"path": "/lib/bare/bundles/bareBluetoothApple.js",
"path": "/lib/bare/bundles/bareBundleCompile.js",
"keys": [
"bareBluetoothApple"
"bareBundleCompile"
]
},
{
@@ -157,48 +145,60 @@
"bareBundle"
]
},
{
"path": "/lib/bare/bundles/bareBuffer.js",
"keys": [
"bareBuffer"
]
},
{
"path": "/lib/bare/bundles/bareBluetoothApple.js",
"keys": [
"bareBluetoothApple"
]
},
{
"path": "/lib/bare/bundles/bareBundleEvaluate.js",
"keys": [
"bareBundleEvaluate"
]
},
{
"path": "/lib/bare/bundles/bareBundleId.js",
"keys": [
"bareBundleId"
]
},
{
"path": "/lib/bare/bundles/bareConsole.js",
"keys": [
"bareConsole"
]
},
{
"path": "/lib/bare/bundles/bareDaemon.js",
"keys": [
"bareDaemon"
]
},
{
"path": "/lib/bare/bundles/bareChannel.js",
"keys": [
"bareChannel"
]
},
{
"path": "/lib/bare/bundles/bareBoot.js",
"keys": [
"bareBoot"
]
},
{
"path": "/lib/bare/bundles/bareDaemon.js",
"keys": [
"bareDaemon"
]
},
{
"path": "/lib/bare/bundles/bareConsole.js",
"keys": [
"bareConsole"
]
},
{
"path": "/lib/bare/bundles/bareBundleId.js",
"keys": [
"bareBundleId"
]
},
{
"path": "/lib/bare/bundles/bareDebugLog.js",
"keys": [
"bareDebugLog"
]
},
{
"path": "/lib/bare/bundles/bareChannel.js",
"keys": [
"bareChannel"
]
},
{
"path": "/lib/bare/bundles/bareDelta.js",
"keys": [
@@ -218,15 +218,15 @@
]
},
{
"path": "/lib/bare/bundles/bareEnv.js",
"path": "/lib/bare/bundles/bareCov.js",
"keys": [
"bareEnv"
"bareCov"
]
},
{
"path": "/lib/bare/bundles/bareDgram.js",
"path": "/lib/bare/bundles/bareEnv.js",
"keys": [
"bareDgram"
"bareEnv"
]
},
{
@@ -236,27 +236,9 @@
]
},
{
"path": "/lib/bare/bundles/bareCov.js",
"path": "/lib/bare/bundles/bareDgram.js",
"keys": [
"bareCov"
]
},
{
"path": "/lib/bare/bundles/bareFfmpeg.js",
"keys": [
"bareFfmpeg"
]
},
{
"path": "/lib/bare/bundles/bareFormData.js",
"keys": [
"bareFormData"
]
},
{
"path": "/lib/bare/bundles/bareFileLogger.js",
"keys": [
"bareFileLogger"
"bareDgram"
]
},
{
@@ -266,9 +248,15 @@
]
},
{
"path": "/lib/bare/bundles/bareGif.js",
"path": "/lib/bare/bundles/bareFormData.js",
"keys": [
"bareGif"
"bareFormData"
]
},
{
"path": "/lib/bare/bundles/bareFfmpeg.js",
"keys": [
"bareFfmpeg"
]
},
{
@@ -278,15 +266,9 @@
]
},
{
"path": "/lib/bare/bundles/bareFs.js",
"path": "/lib/bare/bundles/bareFileLogger.js",
"keys": [
"bareFs"
]
},
{
"path": "/lib/bare/bundles/bareGtk.js",
"keys": [
"bareGtk"
"bareFileLogger"
]
},
{
@@ -296,9 +278,15 @@
]
},
{
"path": "/lib/bare/bundles/bareHttpParser.js",
"path": "/lib/bare/bundles/bareGtk.js",
"keys": [
"bareHttpParser"
"bareGtk"
]
},
{
"path": "/lib/bare/bundles/bareGif.js",
"keys": [
"bareGif"
]
},
{
@@ -308,9 +296,15 @@
]
},
{
"path": "/lib/bare/bundles/bareHttp1.js",
"path": "/lib/bare/bundles/bareFs.js",
"keys": [
"bareHttp1"
"bareFs"
]
},
{
"path": "/lib/bare/bundles/bareHttpParser.js",
"keys": [
"bareHttpParser"
]
},
{
@@ -325,6 +319,12 @@
"bareIco"
]
},
{
"path": "/lib/bare/bundles/bareHttp1.js",
"keys": [
"bareHttp1"
]
},
{
"path": "/lib/bare/bundles/bareInspect.js",
"keys": [
@@ -337,12 +337,6 @@
"bareHttps"
]
},
{
"path": "/lib/bare/bundles/bareIntl.js",
"keys": [
"bareIntl"
]
},
{
"path": "/lib/bare/bundles/bareJpeg.js",
"keys": [
@@ -350,9 +344,9 @@
]
},
{
"path": "/lib/bare/bundles/bareIpc.js",
"path": "/lib/bare/bundles/bareIntl.js",
"keys": [
"bareIpc"
"bareIntl"
]
},
{
@@ -362,15 +356,9 @@
]
},
{
"path": "/lib/bare/bundles/bareLogger.js",
"path": "/lib/bare/bundles/bareIpc.js",
"keys": [
"bareLogger"
]
},
{
"path": "/lib/bare/bundles/bareLink.js",
"keys": [
"bareLink"
"bareIpc"
]
},
{
@@ -380,9 +368,21 @@
]
},
{
"path": "/lib/bare/bundles/bareModuleLexer.js",
"path": "/lib/bare/bundles/bareLink.js",
"keys": [
"bareModuleLexer"
"bareLink"
]
},
{
"path": "/lib/bare/bundles/bareLogger.js",
"keys": [
"bareLogger"
]
},
{
"path": "/lib/bare/bundles/bareModule.js",
"keys": [
"bareModule"
]
},
{
@@ -398,21 +398,9 @@
]
},
{
"path": "/lib/bare/bundles/bareModule.js",
"path": "/lib/bare/bundles/bareModuleLexer.js",
"keys": [
"bareModule"
]
},
{
"path": "/lib/bare/bundles/bareModuleTraverse.js",
"keys": [
"bareModuleTraverse"
]
},
{
"path": "/lib/bare/bundles/bareNative.js",
"keys": [
"bareNative"
"bareModuleLexer"
]
},
{
@@ -421,6 +409,12 @@
"bareNdk"
]
},
{
"path": "/lib/bare/bundles/bareNative.js",
"keys": [
"bareNative"
]
},
{
"path": "/lib/bare/bundles/bareNodeFetch.js",
"keys": [
@@ -428,9 +422,9 @@
]
},
{
"path": "/lib/bare/bundles/bareMedia.js",
"path": "/lib/bare/bundles/bareModuleTraverse.js",
"keys": [
"bareMedia"
"bareModuleTraverse"
]
},
{
@@ -439,36 +433,18 @@
"bareOpen"
]
},
{
"path": "/lib/bare/bundles/bareMedia.js",
"keys": [
"bareMedia"
]
},
{
"path": "/lib/bare/bundles/bareOs.js",
"keys": [
"bareOs"
]
},
{
"path": "/lib/bare/bundles/bareNet.js",
"keys": [
"bareNet"
]
},
{
"path": "/lib/bare/bundles/barePackDrive.js",
"keys": [
"barePackDrive"
]
},
{
"path": "/lib/bare/bundles/barePerformance.js",
"keys": [
"barePerformance"
]
},
{
"path": "/lib/bare/bundles/barePack.js",
"keys": [
"barePack"
]
},
{
"path": "/lib/bare/bundles/bareDev.js",
"keys": [
@@ -476,15 +452,27 @@
]
},
{
"path": "/lib/bare/bundles/barePng.js",
"path": "/lib/bare/bundles/barePerformance.js",
"keys": [
"barePng"
"barePerformance"
]
},
{
"path": "/lib/bare/bundles/barePipe.js",
"path": "/lib/bare/bundles/barePackDrive.js",
"keys": [
"barePipe"
"barePackDrive"
]
},
{
"path": "/lib/bare/bundles/barePack.js",
"keys": [
"barePack"
]
},
{
"path": "/lib/bare/bundles/bareNet.js",
"keys": [
"bareNet"
]
},
{
@@ -494,9 +482,9 @@
]
},
{
"path": "/lib/bare/bundles/barePrebuild.js",
"path": "/lib/bare/bundles/barePng.js",
"keys": [
"barePrebuild"
"barePng"
]
},
{
@@ -506,9 +494,9 @@
]
},
{
"path": "/lib/bare/bundles/bareProcess.js",
"path": "/lib/bare/bundles/barePrebuild.js",
"keys": [
"bareProcess"
"barePrebuild"
]
},
{
@@ -518,9 +506,9 @@
]
},
{
"path": "/lib/bare/bundles/bareRealm.js",
"path": "/lib/bare/bundles/barePipe.js",
"keys": [
"bareRealm"
"barePipe"
]
},
{
@@ -530,9 +518,15 @@
]
},
{
"path": "/lib/bare/bundles/bareRuntime.js",
"path": "/lib/bare/bundles/bareProcess.js",
"keys": [
"bareRuntime"
"bareProcess"
]
},
{
"path": "/lib/bare/bundles/bareRealm.js",
"keys": [
"bareRealm"
]
},
{
@@ -542,27 +536,9 @@
]
},
{
"path": "/lib/bare/bundles/bareRpc.js",
"path": "/lib/bare/bundles/bareRuntime.js",
"keys": [
"bareRpc"
]
},
{
"path": "/lib/bare/bundles/bareRun.js",
"keys": [
"bareRun"
]
},
{
"path": "/lib/bare/bundles/bareRepl.js",
"keys": [
"bareRepl"
]
},
{
"path": "/lib/bare/bundles/bareSemver.js",
"keys": [
"bareSemver"
"bareRuntime"
]
},
{
@@ -571,12 +547,36 @@
"bareSdl"
]
},
{
"path": "/lib/bare/bundles/bareSemver.js",
"keys": [
"bareSemver"
]
},
{
"path": "/lib/bare/bundles/bareRpc.js",
"keys": [
"bareRpc"
]
},
{
"path": "/lib/bare/bundles/bareRepl.js",
"keys": [
"bareRepl"
]
},
{
"path": "/lib/bare/bundles/bareSidecar.js",
"keys": [
"bareSidecar"
]
},
{
"path": "/lib/bare/bundles/bareRun.js",
"keys": [
"bareRun"
]
},
{
"path": "/lib/bare/bundles/bareSignals.js",
"keys": [
@@ -595,24 +595,6 @@
"bareStream"
]
},
{
"path": "/lib/bare/bundles/bareStorage.js",
"keys": [
"bareStorage"
]
},
{
"path": "/lib/bare/bundles/bareSubprocess.js",
"keys": [
"bareSubprocess"
]
},
{
"path": "/lib/bare/bundles/bareStructuredClone.js",
"keys": [
"bareStructuredClone"
]
},
{
"path": "/lib/bare/bundles/bareStdio.js",
"keys": [
@@ -626,15 +608,21 @@
]
},
{
"path": "/lib/bare/bundles/bareTiff.js",
"path": "/lib/bare/bundles/bareStructuredClone.js",
"keys": [
"bareTiff"
"bareStructuredClone"
]
},
{
"path": "/lib/bare/bundles/bareTap.js",
"path": "/lib/bare/bundles/bareStorage.js",
"keys": [
"bareTap"
"bareStorage"
]
},
{
"path": "/lib/bare/bundles/bareSubprocess.js",
"keys": [
"bareSubprocess"
]
},
{
@@ -643,12 +631,42 @@
"bareSystemLogger"
]
},
{
"path": "/lib/bare/bundles/bareTap.js",
"keys": [
"bareTap"
]
},
{
"path": "/lib/bare/bundles/bareTiff.js",
"keys": [
"bareTiff"
]
},
{
"path": "/lib/bare/bundles/bareThread.js",
"keys": [
"bareThread"
]
},
{
"path": "/lib/bare/bundles/bareTimers.js",
"keys": [
"bareTimers"
]
},
{
"path": "/lib/bare/bundles/bareTpl.js",
"keys": [
"bareTpl"
]
},
{
"path": "/lib/bare/bundles/bareType.js",
"keys": [
"bareType"
]
},
{
"path": "/lib/bare/bundles/bareTcp.js",
"keys": [
@@ -661,36 +679,6 @@
"bareTls"
]
},
{
"path": "/lib/bare/bundles/bareThread.js",
"keys": [
"bareThread"
]
},
{
"path": "/lib/bare/bundles/bareType.js",
"keys": [
"bareType"
]
},
{
"path": "/lib/bare/bundles/bareTpl.js",
"keys": [
"bareTpl"
]
},
{
"path": "/lib/bare/bundles/bareUiKit.js",
"keys": [
"bareUiKit"
]
},
{
"path": "/lib/bare/bundles/bareUnpack.js",
"keys": [
"bareUnpack"
]
},
{
"path": "/lib/bare/bundles/bareTty.js",
"keys": [
@@ -703,12 +691,30 @@
"bareV8"
]
},
{
"path": "/lib/bare/bundles/bareUnpack.js",
"keys": [
"bareUnpack"
]
},
{
"path": "/lib/bare/bundles/bareUnionBundle.js",
"keys": [
"bareUnionBundle"
]
},
{
"path": "/lib/bare/bundles/bareUiKit.js",
"keys": [
"bareUiKit"
]
},
{
"path": "/lib/bare/bundles/bareUtils.js",
"keys": [
"bareUtils"
]
},
{
"path": "/lib/bare/bundles/bareVm.js",
"keys": [
@@ -727,6 +733,12 @@
"bareV8ToIstanbul"
]
},
{
"path": "/lib/bare/bundles/bareWebKit.js",
"keys": [
"bareWebKit"
]
},
{
"path": "/lib/bare/bundles/bareWebp.js",
"keys": [
@@ -739,18 +751,6 @@
"bareWebKitGtk"
]
},
{
"path": "/lib/bare/bundles/bareUtils.js",
"keys": [
"bareUtils"
]
},
{
"path": "/lib/bare/bundles/bareWebKit.js",
"keys": [
"bareWebKit"
]
},
{
"path": "/lib/bare/bundles/bareWhich.js",
"keys": [
@@ -775,6 +775,12 @@
"bareZlib"
]
},
{
"path": "/lib/bare/bundles/bareWorker.js",
"keys": [
"bareWorker"
]
},
{
"path": "/lib/bare/bundles/bareZmq.js",
"keys": [
@@ -786,12 +792,6 @@
"keys": [
"bareWs"
]
},
{
"path": "/lib/bare/bundles/bareWorker.js",
"keys": [
"bareWorker"
]
}
],
"bundleStats": {
@@ -1595,8 +1595,8 @@
],
"bundleProvenance": {
"schemaVersion": 1,
"generatedAt": "2026-04-06T03:20:32.232Z",
"gitCommit": "72e0c9c881ec9702ce6f100d781b8045a6a5093b",
"generatedAt": "2026-04-06T10:31:01.446Z",
"gitCommit": "140b17c5fdd1ff1dc5da3cf9b6ae63dc6de5fc0e",
"nodeVersion": "v22.22.0",
"bundleTier": "all",
"normativeManifest": "packages/bare-os-booter/lib/bare-module-manifest.json",
kernel/lib/bare/shell-completion.json
+1 -1
View File
@@ -1,6 +1,6 @@
{
"schema": 1,
"atMs": 1775445631090,
"atMs": 1775471460373,
"commands": [
"arch",
"awk",
kernel/share/man/man.json
+1 -1
View File
File diff suppressed because one or more lines are too long
packages/bare-os-bare-libs/README.md
+3 -1
View File
@@ -6,7 +6,9 @@ Builds trusted IIFE bundles from [`bare-module-manifest.json`](../bare-os-booter
- `kernel/lib/bare/manifest.json` (paths for the booter drive merge)
- Mirrored under `packages/bare-os-seeder/kernel/lib/bare/` for seeder parity
**Documentation:** [Developer guide ch.12 — Bare modules](../../developer-guide/12-bare-modules-and-pear-ecosystem.md) · [Kernel tree — `lib/bare`](../../kernel/README.md) · [docs/README — catalog](../../docs/README.md).
**When to use:** run this build after changing **`bare-module-manifest.json`**, bumping Holepunch catalog entries, or refreshing upstream **`bare-*`** packages — **`pretest`** expects **`kernel/lib/bare/bundles`** and **`bundle-health.json`** to match.
**Documentation:** [Developer guide ch.12 — Bare modules](../../developer-guide/12-bare-modules-and-pear-ecosystem.md) · [Kernel extensions](../../docs/reference/kernel-extensions.md) · [Kernel tree — `lib/bare`](../../kernel/README.md).
Run from repo root:
packages/bare-os-booter/README.md
+3 -1
View File
@@ -4,7 +4,9 @@
There is **no local seed fallback** — a running seeder (or another peer with the image) must be reachable within `BARE_OS_BOOT_TIMEOUT_MS`.
**Documentation:** [User manual](../../users-manual/README.md) (run and operate) · [Handbook](../../handbook/README.md) (architecture) · [Developer guide](../../developer-guide/README.md) (extend `ctx` and `/bin`) · [Booter reference](../../docs/reference/package-bare-os-booter.md) (paths and env appendix pointers) · [CHANGELOG](./CHANGELOG.md) (`bareOsCtxApiVersion`).
**When to use:** run the booter to **consume** the replicated image and start an interactive session (typical dev: second terminal with **`npm run os:booter`**).
**Documentation:** [Concepts — Two drives](../../docs/concepts/two-drive-model.md) · [Booter reference](../../docs/reference/package-bare-os-booter.md) · [Developer guide §2 — `ctx`](../../developer-guide/02-the-context-object.md) · [CHANGELOG](./CHANGELOG.md) (`bareOsCtxApiVersion`).
## Run
packages/bare-os-coreutils/README.md
+3 -1
View File
@@ -5,7 +5,9 @@
- `kernel/bin/<command>` — staged into the **system** Hyperdrive as `/bin/*`
- `packages/bare-os-seeder/kernel/bin/<command>` — **vendored** copy for Pear bundles (seeder has no sibling `bare-os-coreutils` at runtime)
**Documentation:** [User manual](../../users-manual/README.md) · [Developer guide — extending `/bin`](../../developer-guide/06-extending-bin-coreutils.md) · [Coreutils reference](../../docs/reference/package-bare-os-coreutils-and-ci.md) · [Handbook ch.9](../../handbook/09-posix-utilities-shell-and-vfs.md).
**When to use:** run **`npm run build -w bare-os-coreutils`** whenever you change **`src/*.js`**, **`lib/commands.mjs`**, or **`man/pages/*`** so **`kernel/bin/*`** and **`man.json`** stay in sync before **`pretest`** or **`pear run`**.
**Documentation:** [Concepts — POSIX](../../docs/concepts/posix-stance.md) · [Developer guide — extending `/bin`](../../developer-guide/06-extending-bin-coreutils.md) · [Coreutils reference](../../docs/reference/package-bare-os-coreutils-and-ci.md) · [Handbook ch.9](../../handbook/09-posix-utilities-shell-and-vfs.md).
## Command contract
packages/bare-os-lscolors/README.md
+7
View File
@@ -0,0 +1,7 @@
# bare-os-lscolors
**When to use:** this workspace is a **shared helper** for parsing **`LS_COLORS`** / **`dircolors`** data. You normally **do not** import it directly from apps — **`bare-os-coreutils`** (for **`ls`** / **`dircolors`**) and **`bare-os-booter`** (theme integration) consume it.
**Documentation:** [Handbook ch.9 — POSIX utilities](../../handbook/09-posix-utilities-shell-and-vfs.md) · [docs/themes/README.md](../../docs/themes/README.md) · [bare-os-coreutils README](../bare-os-coreutils/README.md).
**Entry:** [`bare-os-lscolors.js`](bare-os-lscolors.js) (see `package.json` **`exports`**).
packages/bare-os-protocol/README.md
+12 -1
View File
@@ -2,7 +2,18 @@
Shared **wire format and constants** for the Bare operating system monorepo: Hyperswarm topic, 512-byte MBR layout, and Protomux **bare-os-v1** seed-channel message shapes.
**Documentation:** [Protocol reference](../../docs/reference/package-bare-os-protocol.md) · [Kernel extensions](../../docs/reference/kernel-extensions.md) · [Handbook ch.3](../../handbook/03-protocol-and-disk.md).
**When to use:** depend on this package when building a **compatible seeder or booter**, fuzz-testing **MBR/topic** stability, or reusing **kernel feature bit** masks in tooling.
**Documentation:** [Concepts — P2P](../../docs/concepts/p2p-swarm-and-protomux.md) · [Protocol reference](../../docs/reference/package-bare-os-protocol.md) · [Handbook ch.3](../../handbook/03-protocol-and-disk.md) · [Kernel extensions](../../docs/reference/kernel-extensions.md).
```mermaid
flowchart LR
T[bare-os-v1 topic]
C[Protomux channel]
M[MBR block 0]
T --> C
M --> H[Hyperdrive keys]
```
## What it provides
packages/bare-os-seeder/README.md
+3 -1
View File
@@ -2,7 +2,9 @@
**Pear / Bare application** that owns the **canonical system Hyperdrive**: it walks a kernel tree on disk, writes `/boot/init.js`, `/bin/*`, `/etc/*` into the drive (no host temp dirs), builds a **512-byte MBR** with the drive key, joins **Hyperswarm** on `bare-os-v1`, and serves MBR block reads + **Protomux** `bare-os-v1` replication to peers.
**Documentation:** [User manual](../../users-manual/README.md) · [Handbook](../../handbook/README.md) · [Seeder reference](../../docs/reference/package-bare-os-seeder.md) · [Protocol reference](../../docs/reference/package-bare-os-protocol.md).
**When to use:** run the seeder when you want to **publish** the system image for booters to replicate (typical dev: one terminal with **`npm run os:seeder`**).
**Documentation:** [Concepts — Boot](../../docs/concepts/boot-and-init-timeline.md) · [Seeder reference](../../docs/reference/package-bare-os-seeder.md) · [User manual ch.3](../../users-manual/03-running-seeder-and-booter.md) · [Protocol reference](../../docs/reference/package-bare-os-protocol.md).
## Run
packages/bare-os-seeder/kernel/README.md
+1 -1
View File
@@ -4,7 +4,7 @@ Files in this directory are **read from disk by the seeder** (or copied into `pa
**This `README.md` file** only documents the tree layout in the repository; the seeder **does not** install it as **`/README.md`** on the image (so the guest root directory stays free of repo docs).
**Documentation:** [User manual](../users-manual/README.md) · [Handbook](../handbook/README.md) · [Kernel image reference](../docs/reference/kernel-image.md) · [Developer guide](../developer-guide/README.md).
**Documentation:** [Concepts — Boot](../docs/concepts/boot-and-init-timeline.md) · [User manual](../users-manual/README.md) · [Handbook](../handbook/README.md) · [Kernel image reference](../docs/reference/kernel-image.md) · [Developer guide](../developer-guide/README.md).
## Staging map (seeder)
packages/bare-os-seeder/kernel/etc/bare-os/posix_utilities.json
+1 -1
View File
@@ -1,7 +1,7 @@
{
"schema": 2,
"profileId": "bare-os-posix-like",
"generatedAt": "2026-04-06T03:20:31.090Z",
"generatedAt": "2026-04-06T10:31:00.374Z",
"note": "Sparse POSIX Issue 7 coverage hints for /bin utilities. Omitted command names are not yet profiled here.",
"commandIndex": [
{
packages/bare-os-seeder/kernel/lib/bare/manifest.json
+260 -260
View File
@@ -25,12 +25,6 @@
"compactEncoding"
]
},
{
"path": "/lib/bare/bundles/protomux.js",
"keys": [
"protomux"
]
},
{
"path": "/lib/bare/bundles/bareUrl.js",
"keys": [
@@ -49,6 +43,12 @@
"bareEncoding"
]
},
{
"path": "/lib/bare/bundles/protomux.js",
"keys": [
"protomux"
]
},
{
"path": "/lib/bare/bundles/bareEvents.js",
"keys": [
@@ -68,15 +68,9 @@
]
},
{
"path": "/lib/bare/bundles/bareCrypto.js",
"path": "/lib/bare/bundles/bareAnsiEscapes.js",
"keys": [
"bareCrypto"
]
},
{
"path": "/lib/bare/bundles/bareReadline.js",
"keys": [
"bareReadline"
"bareAnsiEscapes"
]
},
{
@@ -86,27 +80,15 @@
]
},
{
"path": "/lib/bare/bundles/fetch.js",
"path": "/lib/bare/bundles/bareReadline.js",
"keys": [
"fetch"
"bareReadline"
]
},
{
"path": "/lib/bare/bundles/bareAnsiEscapes.js",
"path": "/lib/bare/bundles/bareCrypto.js",
"keys": [
"bareAnsiEscapes"
]
},
{
"path": "/lib/bare/bundles/bareAsyncHooks.js",
"keys": [
"bareAsyncHooks"
]
},
{
"path": "/lib/bare/bundles/bareAssert.js",
"keys": [
"bareAssert"
"bareCrypto"
]
},
{
@@ -121,6 +103,12 @@
"bareAppKit"
]
},
{
"path": "/lib/bare/bundles/bareAsyncHooks.js",
"keys": [
"bareAsyncHooks"
]
},
{
"path": "/lib/bare/bundles/bareAtomics.js",
"keys": [
@@ -128,9 +116,9 @@
]
},
{
"path": "/lib/bare/bundles/bareBuffer.js",
"path": "/lib/bare/bundles/bareAssert.js",
"keys": [
"bareBuffer"
"bareAssert"
]
},
{
@@ -140,15 +128,15 @@
]
},
{
"path": "/lib/bare/bundles/bareBundleCompile.js",
"path": "/lib/bare/bundles/fetch.js",
"keys": [
"bareBundleCompile"
"fetch"
]
},
{
"path": "/lib/bare/bundles/bareBluetoothApple.js",
"path": "/lib/bare/bundles/bareBundleCompile.js",
"keys": [
"bareBluetoothApple"
"bareBundleCompile"
]
},
{
@@ -157,48 +145,60 @@
"bareBundle"
]
},
{
"path": "/lib/bare/bundles/bareBuffer.js",
"keys": [
"bareBuffer"
]
},
{
"path": "/lib/bare/bundles/bareBluetoothApple.js",
"keys": [
"bareBluetoothApple"
]
},
{
"path": "/lib/bare/bundles/bareBundleEvaluate.js",
"keys": [
"bareBundleEvaluate"
]
},
{
"path": "/lib/bare/bundles/bareBundleId.js",
"keys": [
"bareBundleId"
]
},
{
"path": "/lib/bare/bundles/bareConsole.js",
"keys": [
"bareConsole"
]
},
{
"path": "/lib/bare/bundles/bareDaemon.js",
"keys": [
"bareDaemon"
]
},
{
"path": "/lib/bare/bundles/bareChannel.js",
"keys": [
"bareChannel"
]
},
{
"path": "/lib/bare/bundles/bareBoot.js",
"keys": [
"bareBoot"
]
},
{
"path": "/lib/bare/bundles/bareDaemon.js",
"keys": [
"bareDaemon"
]
},
{
"path": "/lib/bare/bundles/bareConsole.js",
"keys": [
"bareConsole"
]
},
{
"path": "/lib/bare/bundles/bareBundleId.js",
"keys": [
"bareBundleId"
]
},
{
"path": "/lib/bare/bundles/bareDebugLog.js",
"keys": [
"bareDebugLog"
]
},
{
"path": "/lib/bare/bundles/bareChannel.js",
"keys": [
"bareChannel"
]
},
{
"path": "/lib/bare/bundles/bareDelta.js",
"keys": [
@@ -218,15 +218,15 @@
]
},
{
"path": "/lib/bare/bundles/bareEnv.js",
"path": "/lib/bare/bundles/bareCov.js",
"keys": [
"bareEnv"
"bareCov"
]
},
{
"path": "/lib/bare/bundles/bareDgram.js",
"path": "/lib/bare/bundles/bareEnv.js",
"keys": [
"bareDgram"
"bareEnv"
]
},
{
@@ -236,27 +236,9 @@
]
},
{
"path": "/lib/bare/bundles/bareCov.js",
"path": "/lib/bare/bundles/bareDgram.js",
"keys": [
"bareCov"
]
},
{
"path": "/lib/bare/bundles/bareFfmpeg.js",
"keys": [
"bareFfmpeg"
]
},
{
"path": "/lib/bare/bundles/bareFormData.js",
"keys": [
"bareFormData"
]
},
{
"path": "/lib/bare/bundles/bareFileLogger.js",
"keys": [
"bareFileLogger"
"bareDgram"
]
},
{
@@ -266,9 +248,15 @@
]
},
{
"path": "/lib/bare/bundles/bareGif.js",
"path": "/lib/bare/bundles/bareFormData.js",
"keys": [
"bareGif"
"bareFormData"
]
},
{
"path": "/lib/bare/bundles/bareFfmpeg.js",
"keys": [
"bareFfmpeg"
]
},
{
@@ -278,15 +266,9 @@
]
},
{
"path": "/lib/bare/bundles/bareFs.js",
"path": "/lib/bare/bundles/bareFileLogger.js",
"keys": [
"bareFs"
]
},
{
"path": "/lib/bare/bundles/bareGtk.js",
"keys": [
"bareGtk"
"bareFileLogger"
]
},
{
@@ -296,9 +278,15 @@
]
},
{
"path": "/lib/bare/bundles/bareHttpParser.js",
"path": "/lib/bare/bundles/bareGtk.js",
"keys": [
"bareHttpParser"
"bareGtk"
]
},
{
"path": "/lib/bare/bundles/bareGif.js",
"keys": [
"bareGif"
]
},
{
@@ -308,9 +296,15 @@
]
},
{
"path": "/lib/bare/bundles/bareHttp1.js",
"path": "/lib/bare/bundles/bareFs.js",
"keys": [
"bareHttp1"
"bareFs"
]
},
{
"path": "/lib/bare/bundles/bareHttpParser.js",
"keys": [
"bareHttpParser"
]
},
{
@@ -325,6 +319,12 @@
"bareIco"
]
},
{
"path": "/lib/bare/bundles/bareHttp1.js",
"keys": [
"bareHttp1"
]
},
{
"path": "/lib/bare/bundles/bareInspect.js",
"keys": [
@@ -337,12 +337,6 @@
"bareHttps"
]
},
{
"path": "/lib/bare/bundles/bareIntl.js",
"keys": [
"bareIntl"
]
},
{
"path": "/lib/bare/bundles/bareJpeg.js",
"keys": [
@@ -350,9 +344,9 @@
]
},
{
"path": "/lib/bare/bundles/bareIpc.js",
"path": "/lib/bare/bundles/bareIntl.js",
"keys": [
"bareIpc"
"bareIntl"
]
},
{
@@ -362,15 +356,9 @@
]
},
{
"path": "/lib/bare/bundles/bareLogger.js",
"path": "/lib/bare/bundles/bareIpc.js",
"keys": [
"bareLogger"
]
},
{
"path": "/lib/bare/bundles/bareLink.js",
"keys": [
"bareLink"
"bareIpc"
]
},
{
@@ -380,9 +368,21 @@
]
},
{
"path": "/lib/bare/bundles/bareModuleLexer.js",
"path": "/lib/bare/bundles/bareLink.js",
"keys": [
"bareModuleLexer"
"bareLink"
]
},
{
"path": "/lib/bare/bundles/bareLogger.js",
"keys": [
"bareLogger"
]
},
{
"path": "/lib/bare/bundles/bareModule.js",
"keys": [
"bareModule"
]
},
{
@@ -398,21 +398,9 @@
]
},
{
"path": "/lib/bare/bundles/bareModule.js",
"path": "/lib/bare/bundles/bareModuleLexer.js",
"keys": [
"bareModule"
]
},
{
"path": "/lib/bare/bundles/bareModuleTraverse.js",
"keys": [
"bareModuleTraverse"
]
},
{
"path": "/lib/bare/bundles/bareNative.js",
"keys": [
"bareNative"
"bareModuleLexer"
]
},
{
@@ -421,6 +409,12 @@
"bareNdk"
]
},
{
"path": "/lib/bare/bundles/bareNative.js",
"keys": [
"bareNative"
]
},
{
"path": "/lib/bare/bundles/bareNodeFetch.js",
"keys": [
@@ -428,9 +422,9 @@
]
},
{
"path": "/lib/bare/bundles/bareMedia.js",
"path": "/lib/bare/bundles/bareModuleTraverse.js",
"keys": [
"bareMedia"
"bareModuleTraverse"
]
},
{
@@ -439,36 +433,18 @@
"bareOpen"
]
},
{
"path": "/lib/bare/bundles/bareMedia.js",
"keys": [
"bareMedia"
]
},
{
"path": "/lib/bare/bundles/bareOs.js",
"keys": [
"bareOs"
]
},
{
"path": "/lib/bare/bundles/bareNet.js",
"keys": [
"bareNet"
]
},
{
"path": "/lib/bare/bundles/barePackDrive.js",
"keys": [
"barePackDrive"
]
},
{
"path": "/lib/bare/bundles/barePerformance.js",
"keys": [
"barePerformance"
]
},
{
"path": "/lib/bare/bundles/barePack.js",
"keys": [
"barePack"
]
},
{
"path": "/lib/bare/bundles/bareDev.js",
"keys": [
@@ -476,15 +452,27 @@
]
},
{
"path": "/lib/bare/bundles/barePng.js",
"path": "/lib/bare/bundles/barePerformance.js",
"keys": [
"barePng"
"barePerformance"
]
},
{
"path": "/lib/bare/bundles/barePipe.js",
"path": "/lib/bare/bundles/barePackDrive.js",
"keys": [
"barePipe"
"barePackDrive"
]
},
{
"path": "/lib/bare/bundles/barePack.js",
"keys": [
"barePack"
]
},
{
"path": "/lib/bare/bundles/bareNet.js",
"keys": [
"bareNet"
]
},
{
@@ -494,9 +482,9 @@
]
},
{
"path": "/lib/bare/bundles/barePrebuild.js",
"path": "/lib/bare/bundles/barePng.js",
"keys": [
"barePrebuild"
"barePng"
]
},
{
@@ -506,9 +494,9 @@
]
},
{
"path": "/lib/bare/bundles/bareProcess.js",
"path": "/lib/bare/bundles/barePrebuild.js",
"keys": [
"bareProcess"
"barePrebuild"
]
},
{
@@ -518,9 +506,9 @@
]
},
{
"path": "/lib/bare/bundles/bareRealm.js",
"path": "/lib/bare/bundles/barePipe.js",
"keys": [
"bareRealm"
"barePipe"
]
},
{
@@ -530,9 +518,15 @@
]
},
{
"path": "/lib/bare/bundles/bareRuntime.js",
"path": "/lib/bare/bundles/bareProcess.js",
"keys": [
"bareRuntime"
"bareProcess"
]
},
{
"path": "/lib/bare/bundles/bareRealm.js",
"keys": [
"bareRealm"
]
},
{
@@ -542,27 +536,9 @@
]
},
{
"path": "/lib/bare/bundles/bareRpc.js",
"path": "/lib/bare/bundles/bareRuntime.js",
"keys": [
"bareRpc"
]
},
{
"path": "/lib/bare/bundles/bareRun.js",
"keys": [
"bareRun"
]
},
{
"path": "/lib/bare/bundles/bareRepl.js",
"keys": [
"bareRepl"
]
},
{
"path": "/lib/bare/bundles/bareSemver.js",
"keys": [
"bareSemver"
"bareRuntime"
]
},
{
@@ -571,12 +547,36 @@
"bareSdl"
]
},
{
"path": "/lib/bare/bundles/bareSemver.js",
"keys": [
"bareSemver"
]
},
{
"path": "/lib/bare/bundles/bareRpc.js",
"keys": [
"bareRpc"
]
},
{
"path": "/lib/bare/bundles/bareRepl.js",
"keys": [
"bareRepl"
]
},
{
"path": "/lib/bare/bundles/bareSidecar.js",
"keys": [
"bareSidecar"
]
},
{
"path": "/lib/bare/bundles/bareRun.js",
"keys": [
"bareRun"
]
},
{
"path": "/lib/bare/bundles/bareSignals.js",
"keys": [
@@ -595,24 +595,6 @@
"bareStream"
]
},
{
"path": "/lib/bare/bundles/bareStorage.js",
"keys": [
"bareStorage"
]
},
{
"path": "/lib/bare/bundles/bareSubprocess.js",
"keys": [
"bareSubprocess"
]
},
{
"path": "/lib/bare/bundles/bareStructuredClone.js",
"keys": [
"bareStructuredClone"
]
},
{
"path": "/lib/bare/bundles/bareStdio.js",
"keys": [
@@ -626,15 +608,21 @@
]
},
{
"path": "/lib/bare/bundles/bareTiff.js",
"path": "/lib/bare/bundles/bareStructuredClone.js",
"keys": [
"bareTiff"
"bareStructuredClone"
]
},
{
"path": "/lib/bare/bundles/bareTap.js",
"path": "/lib/bare/bundles/bareStorage.js",
"keys": [
"bareTap"
"bareStorage"
]
},
{
"path": "/lib/bare/bundles/bareSubprocess.js",
"keys": [
"bareSubprocess"
]
},
{
@@ -643,12 +631,42 @@
"bareSystemLogger"
]
},
{
"path": "/lib/bare/bundles/bareTap.js",
"keys": [
"bareTap"
]
},
{
"path": "/lib/bare/bundles/bareTiff.js",
"keys": [
"bareTiff"
]
},
{
"path": "/lib/bare/bundles/bareThread.js",
"keys": [
"bareThread"
]
},
{
"path": "/lib/bare/bundles/bareTimers.js",
"keys": [
"bareTimers"
]
},
{
"path": "/lib/bare/bundles/bareTpl.js",
"keys": [
"bareTpl"
]
},
{
"path": "/lib/bare/bundles/bareType.js",
"keys": [
"bareType"
]
},
{
"path": "/lib/bare/bundles/bareTcp.js",
"keys": [
@@ -661,36 +679,6 @@
"bareTls"
]
},
{
"path": "/lib/bare/bundles/bareThread.js",
"keys": [
"bareThread"
]
},
{
"path": "/lib/bare/bundles/bareType.js",
"keys": [
"bareType"
]
},
{
"path": "/lib/bare/bundles/bareTpl.js",
"keys": [
"bareTpl"
]
},
{
"path": "/lib/bare/bundles/bareUiKit.js",
"keys": [
"bareUiKit"
]
},
{
"path": "/lib/bare/bundles/bareUnpack.js",
"keys": [
"bareUnpack"
]
},
{
"path": "/lib/bare/bundles/bareTty.js",
"keys": [
@@ -703,12 +691,30 @@
"bareV8"
]
},
{
"path": "/lib/bare/bundles/bareUnpack.js",
"keys": [
"bareUnpack"
]
},
{
"path": "/lib/bare/bundles/bareUnionBundle.js",
"keys": [
"bareUnionBundle"
]
},
{
"path": "/lib/bare/bundles/bareUiKit.js",
"keys": [
"bareUiKit"
]
},
{
"path": "/lib/bare/bundles/bareUtils.js",
"keys": [
"bareUtils"
]
},
{
"path": "/lib/bare/bundles/bareVm.js",
"keys": [
@@ -727,6 +733,12 @@
"bareV8ToIstanbul"
]
},
{
"path": "/lib/bare/bundles/bareWebKit.js",
"keys": [
"bareWebKit"
]
},
{
"path": "/lib/bare/bundles/bareWebp.js",
"keys": [
@@ -739,18 +751,6 @@
"bareWebKitGtk"
]
},
{
"path": "/lib/bare/bundles/bareUtils.js",
"keys": [
"bareUtils"
]
},
{
"path": "/lib/bare/bundles/bareWebKit.js",
"keys": [
"bareWebKit"
]
},
{
"path": "/lib/bare/bundles/bareWhich.js",
"keys": [
@@ -775,6 +775,12 @@
"bareZlib"
]
},
{
"path": "/lib/bare/bundles/bareWorker.js",
"keys": [
"bareWorker"
]
},
{
"path": "/lib/bare/bundles/bareZmq.js",
"keys": [
@@ -786,12 +792,6 @@
"keys": [
"bareWs"
]
},
{
"path": "/lib/bare/bundles/bareWorker.js",
"keys": [
"bareWorker"
]
}
],
"bundleStats": {
@@ -1595,8 +1595,8 @@
],
"bundleProvenance": {
"schemaVersion": 1,
"generatedAt": "2026-04-06T03:20:32.232Z",
"gitCommit": "72e0c9c881ec9702ce6f100d781b8045a6a5093b",
"generatedAt": "2026-04-06T10:31:01.446Z",
"gitCommit": "140b17c5fdd1ff1dc5da3cf9b6ae63dc6de5fc0e",
"nodeVersion": "v22.22.0",
"bundleTier": "all",
"normativeManifest": "packages/bare-os-booter/lib/bare-module-manifest.json",
packages/bare-os-seeder/kernel/lib/bare/shell-completion.json
+1 -1
View File
@@ -1,6 +1,6 @@
{
"schema": 1,
"atMs": 1775445631090,
"atMs": 1775471460373,
"commands": [
"arch",
"awk",
packages/bare-os-seeder/kernel/share/man/man.json
+1 -1
View File
File diff suppressed because one or more lines are too long
scripts/README.md
+2
View File
@@ -2,6 +2,8 @@
Small **monorepo-level** helpers used by npm scripts and maintainers.
**Release gate:** run **`npm run release-checklist`** from the repo root before tagging — it drives [`release-checklist.mjs`](release-checklist.mjs) (see [docs/release-checklist.md](../docs/release-checklist.md) for the human checklist).
**Documentation hub:** [User manual](../users-manual/README.md) · [Handbook](../handbook/README.md) · [docs/reference](../docs/reference/README.md).
### Maintainer build order (kernel image + parity)
users-manual/01-what-this-is.md
+18
View File
@@ -7,6 +7,7 @@
## On this page
- [The idea in one paragraph](#the-idea-in-one-paragraph)
- [Where does the JavaScript run?](#where-does-the-javascript-run)
- [System drive versus personal drive](#system-drive-versus-personal-drive)
- [How you get the image](#how-you-get-the-image)
- [What you can do inside](#what-you-can-do-inside)
@@ -25,6 +26,23 @@ Bare OS is a **system image** that lives on a **Hyperdrive** and is meant to be
---
## Where does the JavaScript run?
You will hear “**kernel**” and “**/bin**” and picture a metal machine. Here the **booter** (Pear or Node on your **host**) implements **`ctx`**, the VFS, and Hyperswarm. Scripts **on the Hyperdrive** (`/boot/init.js`, `/bin/*`) run as **`AsyncFunction`** bodies inside that process—they **do not** use on-disk ESM **`import`** the way a normal Node project does.
```mermaid
flowchart LR
H[Host Pear or Node booter]
C[ctx vfs swarm bridges]
D[Drive scripts init.js bin]
H --> C
C --> D
```
Read next: [Developer guide — Two runtimes](../developer-guide/01-two-runtimes-host-vs-image.md) · [Concepts — Boot](../docs/concepts/boot-and-init-timeline.md).
---
## System drive versus personal drive
The **system drive** is the replicated OS tree: kernel, `/bin`, `/boot`, and the rest of the staged image. Treat it as **shared** and **replaceable** from the swarm’s point of view.
users-manual/05-home-identity-and-vault.md
+3
View File
@@ -2,6 +2,9 @@
**Prerequisites:** [Shell, PATH, and scripts](04-shell-path-and-scripts.md). **Time to read:** about seven minutes.
> **Important**
> Identity and vault material are **security-sensitive**. Before you rely on them for anything serious, read the **[vault threat model](../docs/security/vault-threat-model.md)** (what the design promises and what it does **not**).
---
## On this page
users-manual/README.md
+2
View File
@@ -2,6 +2,8 @@
This manual is for **people who want to run and use** Bare OS: clone the repo, start a seeder and booter, work in the shell, and understand where your files and identity live. It is written in plain language and points to deeper material when you need it.
Short evergreen explainers (**two drives**, **boot**, **swarm**, **identity**, **POSIX stance**): [docs/concepts/README.md](../docs/concepts/README.md).
Bare OS is **experimental research software**, not a production operating system. It is licensed under **Apache-2.0** ([LICENSE](../LICENSE)).
> **Tip**