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

Docs Update

Browse Source
This commit is contained in:
Raven Scott
2026-04-04 19:51:05 -04:00
parent f8ddef7950
commit c29ec13cf9
47 changed files with 1106 additions and 464 deletions
Download Patch File Download Diff File Expand all files Collapse all files
users-manual/01-what-this-is.md
+47
View File
@@ -20,6 +20,9 @@
Bare OS is a **system image** that lives on a **Hyperdrive** and is meant to be **replicated from peers** (Hyperswarm and Protomux) rather than downloaded from a single HTTP mirror. A **seeder** publishes that drive and a small **MBR** block; a **booter** joins the swarm, opens the drive, and runs **`/boot/init.js`**. Alongside the read-only **system** image, a separate **personal** Hyperdrive holds per-machine state: home directories, identity, logs, and optional extra mounts. The design is **P2P-first** and aligned with Holepunch-style **Bare** and **Pear** runtimes.
> **Note**
> Definitions for bolded terms live in the [canonical glossary](../docs/glossary.md).
---
## System drive versus personal drive
@@ -30,6 +33,25 @@ The **personal drive** is **yours** for that node: guest and user home layouts u
For the protocol layout (MBR, keys, swarm topic names), read [Handbook — Chapter 3: Protocol and disk](../handbook/03-protocol-and-disk.md).
```mermaid
flowchart TB
subgraph systemDrive [System Hyperdrive]
Bin["/bin"]
Boot["/boot/init.js"]
end
subgraph personalDrive [Personal Hyperdrive]
Home["/home/..."]
Bare["/.bare/"]
end
vfs[VFS merge + synthetic /proc /run /sys]
systemDrive --> vfs
personalDrive --> vfs
shell[Shell session]
vfs --> shell
```
![Two-drive VFS conceptual diagram](../docs/images/two-drive-vfs.png)
---
## How you get the image
@@ -42,6 +64,22 @@ In development you typically:
You can run both sides with plain **Node** for quick iteration, or with **Pear** for behavior closer to a released app. The next chapters walk through install and commands; [PEAR-RUN.md](../PEAR-RUN.md) documents published Pear channels and `pear://` links.
```mermaid
sequenceDiagram
participant Dev as Developer host
participant Seeder as bare-os-seeder
participant Swarm as Hyperswarm topic bare-os-v1
participant Booter as bare-os-booter
Dev->>Seeder: start from repo layout
Seeder->>Swarm: publish system drive + MBR
Dev->>Booter: second terminal
Booter->>Swarm: discover peers replicate
Booter->>Booter: open personal drive build VFS
Booter->>Booter: execute /boot/init.js
```
![Seeder and booter sequence](../docs/images/boot-flow.png)
---
## What you can do inside
@@ -64,6 +102,8 @@ Bare OS is **not** a production operating system. APIs, disk formats, and networ
- **System drive vs personal drive** — Already introduced above; the handbook calls out routing rules, **`/.bare/`**, and mount namespaces in [Chapter 5](../handbook/05-identity-vault-and-hdms.md) and [Chapter 3](../handbook/03-protocol-and-disk.md).
- **Stock image** — The tree produced from this repository’s **`kernel/`** plus built **`/bin`** and **`man.json`**, without your custom forks. Capability bits and **`ctx` API** versions describe what the **stock** booter and seeder advertise together; see [compatibility matrix](../docs/reference/compatibility-matrix.md).
For a full A–Z list, use [docs/glossary.md](../docs/glossary.md).
---
## What Bare OS is not
@@ -72,4 +112,11 @@ It is **not** a Linux distribution, a container runtime, or a full hardware OS.
---
## Related reading
- [Chapter 2 — Install and repository layout](02-install-and-repository-layout.md)
- [Documentation home](../docs/README.md)
---
_Previous: [User manual home](README.md)_ · _Next: [Chapter 2 — Install and repository layout](02-install-and-repository-layout.md)_
users-manual/02-install-and-repository-layout.md
+12 -7
View File
@@ -23,6 +23,9 @@
Continuous integration also installs **Bare** globally for tests that touch identity crypto; if you run the full **`npm test`** suite locally, match that setup. Details live in [Handbook — Chapter 7](../handbook/07-operations-and-development.md#continuous-integration-github-actions).
> **Warning**
> Skipping **`npm ci`** at the repo root before Pear runs often causes confusing module resolution errors. Always install from the root unless you know exactly which workspace layout Pear expects.
---
## Clone and install
@@ -43,13 +46,15 @@ Run **`npm test`** when you want to confirm the tree is healthy before you chang
The repository is an **npm workspace** monorepo. These paths matter most when you are running or debugging Bare OS:
- **`kernel/`** — Sources that are staged onto the **system** Hyperdrive by the seeder. A copy is kept under **`packages/bare-os-seeder/kernel/`** for Pear packaging; CI enforces that they stay in sync.
- **`packages/bare-os-protocol`** — Shared protocol constants: swarm topic, MBR layout, Protomux identifiers, kernel feature bits.
- **`packages/bare-os-seeder`** — Publishes the OS drive and joins the swarm so booters can replicate.
- **`packages/bare-os-booter`** — Joins the swarm, opens system and personal drives, constructs the guest runtime, and runs **`/boot/init.js`**.
- **`packages/bare-os-coreutils`** — Sources and build for **`/bin`** utilities and the merged **`man.json`** database.
- **`packages/bare-os-bare-libs`** — Optional **`/lib/bare`** bundles merged into **`ctx.bare`** when enabled.
- **`scripts/`** — Automation: Pear `node_modules` helpers, parity verifiers, catalog generation, release checklist.
| Path | Role |
| --- | --- |
| **`kernel/`** | Sources staged onto the **system** Hyperdrive by the seeder. A copy lives under **`packages/bare-os-seeder/kernel/`** for Pear packaging; CI enforces byte parity. |
| **`packages/bare-os-protocol`** | Shared protocol constants: swarm topic, MBR layout, Protomux identifiers, kernel feature bits. |
| **`packages/bare-os-seeder`** | Publishes the OS drive and joins the swarm so booters can replicate. |
| **`packages/bare-os-booter`** | Joins the swarm, opens system and personal drives, constructs the guest runtime, runs **`/boot/init.js`**. |
| **`packages/bare-os-coreutils`** | Sources and build for **`/bin`** utilities and merged **`man.json`**. |
| **`packages/bare-os-bare-libs`** | Optional **`/lib/bare`** bundles merged into **`ctx.bare`** when enabled. |
| **`scripts/`** | Automation: Pear `node_modules` helpers, parity verifiers, catalog generation, release checklist. |
Each workspace package has its own **README** with package-specific commands. For a file-by-file inventory, use [docs/reference — Repository layout](../docs/reference/repo-layout-and-root.md).
users-manual/03-running-seeder-and-booter.md
+21 -1
View File
@@ -24,6 +24,16 @@ The **booter** owns the **consumer** side: it looks up peers on the same topic,
You almost always run them as **two separate processes** (two terminal tabs or windows). The booter needs a live seeder (or an already-replicated drive) to make progress within its boot timeout.
```mermaid
flowchart LR
Seeder[bare-os-seeder]
Topic[Swarm topic bare-os-v1]
Booter[bare-os-booter]
Seeder -->|publish MBR + blocks| Topic
Booter -->|discover replicate| Topic
Booter --> Init["/boot/init.js"]
```
---
## Run with Node (quick path)
@@ -60,7 +70,8 @@ npm run os:booter
These scripts run **`scripts/ensure-pear-node-modules.mjs`** first so Pear sees **hoisted** workspace dependencies the same way **`npm ci`** does at the repo root. Without that step, **`pear run`** from inside a package directory can miss modules that live at the root **`node_modules`**.
**Do not** type `pear run os:seeder` — **`os:seeder`** is an **npm script name**, not a Pear application name.
> **Important**
> **`os:seeder`** is an **npm script name**, not a Pear app name. Do not type `pear run os:seeder`.
---
@@ -84,6 +95,8 @@ Concrete channel names, keys, versioned links, and host-side environment variabl
Once the booter has replicated enough of the **system** drive, it mounts the **personal** drive (creating one if needed), wires the merged VFS, and executes **`/boot/init.js`**. The stock kernel prints **`/etc/os-release`**, optional **`motd`**, runs **`/etc/bare-os/rc`** and sorted snippets under **`rc.d`**, then enters the interactive shell unless **`BARE_OS_SKIP_REPL`** or **`onboot`** lines consume the session. You do not need to memorize every phase to operate the system; when something fails **during** boot, enable **`BARE_OS_BOOT_TRACE`** (see [environment appendix](../docs/reference/environment-and-posix-appendix.md)) and read the phase lines on stderr.
Canonical **booter boot steps** (**`vfs`** → **`ctx`** → **`repl`** → **`initd`** → **`kernel_invoke`**) are summarized in [KERNEL_CONTRACT](../docs/architecture/KERNEL_CONTRACT.md).
---
## Choosing Node versus Pear
@@ -92,4 +105,11 @@ Once the booter has replicated enough of the **system** drive, it mounts the **p
---
## Related reading
- [docs/troubleshooting.md](../docs/troubleshooting.md)
- [Handbook — Protocol and disk](../handbook/03-protocol-and-disk.md)
---
_Previous: [Chapter 2](02-install-and-repository-layout.md)_ · _Next: [Chapter 4 — Shell, PATH, and scripts](04-shell-path-and-scripts.md)_
users-manual/04-shell-path-and-scripts.md
+12 -1
View File
@@ -23,6 +23,17 @@ The shell and utilities are part of the **guest** runtime built by the booter. T
For POSIX coverage and deliberate gaps, see [Handbook — Chapter 9](../handbook/09-posix-utilities-shell-and-vfs.md).
```mermaid
flowchart LR
line[User types line]
shell[Shell parse expand]
bin["/bin or builtin"]
vfs[VFS read/write]
line --> shell --> bin --> vfs
```
![Shell pipeline diagram](../docs/images/shell-pipeline.png)
---
## How a command runs (conceptually)
@@ -66,7 +77,7 @@ Pipelines and redirects behave like a small Unix (**`ls | wc -c`**, **`echo hell
## Builtins, `/bin`, and `/proc`
The shell implements **builtins** ( **`cd`**, **`export`**, control flow, …) in **`packages/bare-os-booter/lib/shell.js`**. Everything else normally resolves to **`/bin/<name>`** via **`PATH`**. Synthetic trees such as **`/proc/bare_os_features`** expose JSON or text summaries of capabilities and runtime state; they are documented in the [kernel extensions reference](../docs/reference/kernel-extensions.md) and handbook chapters on the booter. If a name does not resolve, verify you are not shadowing a shell builtin and that **`PATH`** includes **`/bin`** (try **`command -v <name>`** when the shell supports it, or **`which <name>`** if installed).
The shell implements **builtins** (**`cd`**, **`export`**, control flow, …) in **`packages/bare-os-booter/lib/shell.js`**. Everything else normally resolves to **`/bin/<name>`** via **`PATH`**. Synthetic trees such as **`/proc/bare_os_features`** expose JSON or text summaries of capabilities and runtime state; they are documented in the [kernel extensions reference](../docs/reference/kernel-extensions.md) and handbook chapters on the booter. If a name does not resolve, verify you are not shadowing a shell builtin and that **`PATH`** includes **`/bin`** (try **`command -v <name>`** when the shell supports it, or **`which <name>`** if installed).
---
users-manual/05-home-identity-and-vault.md
+15
View File
@@ -32,6 +32,20 @@ After a successful login, **`HOME`** moves under **`/home/<public-key-prefix>`**
Cryptographic details are implementation-specific; this manual stays at the behavior level. For prose-level crypto and flow diagrams, read [Handbook — Chapter 5](../handbook/05-identity-vault-and-hdms.md).
```mermaid
stateDiagram-v2
[*] --> Guest
Guest --> Unlocked : login success
Unlocked --> Guest : logout
Unlocked --> Guest : logout --save vault snapshot
Guest --> Unlocked : login existing account
```
![Identity and vault lifecycle](../docs/images/identity-vault-lifecycle.png)
> **Warning**
> If you **`login --new`** and forget the passphrase, ciphertext under **`/.bare/`** is not recoverable. Plan backups before you depend on vault or HDMS workflows.
---
## Where state lives on disk (mental model)
@@ -72,6 +86,7 @@ For subcommands and examples, use **`man hdms`** after seeding an image with a c
- [Handbook — Chapter 5: Identity, vault, and HDMS](../handbook/05-identity-vault-and-hdms.md)
- [docs/reference — Booter package](../docs/reference/package-bare-os-booter.md) (identity-related sections)
- [Developer guide — Security and trust](../developer-guide/09-security-and-trust.md)
- [Glossary — guest, HDMS, personal drive](../docs/glossary.md)
---
users-manual/06-help-man-and-documentation-map.md
+10 -8
View File
@@ -8,7 +8,7 @@
- [`man` inside the image](#man-inside-the-image)
- [`help` and discoverability](#help-and-discoverability)
- [Four documentation trees](#four-documentation-trees)
- [Documentation trees and hubs](#documentation-trees-and-hubs)
- [Where JSON and schemas live](#where-json-and-schemas-live)
- [Regenerating `man.json`](#regenerating-manjson)
- [Searching topics (`man -k`)](#searching-topics-man--k)
@@ -31,16 +31,18 @@ Some commands expose a **`help`** subcommand or usage text aimed at **interactiv
---
## Four documentation trees
## Documentation trees and hubs
These four areas are intentional; each serves a different job:
These areas are intentional; each serves a different job:
1. **User manual** ([users-manual/README.md](README.md)) — run and use Bare OS without reading the whole architecture first.
2. **Handbook** ([handbook/README.md](../handbook/README.md)) — narrative explanation of design, protocol, runtime, identity, POSIX surface, operations, and research context.
3. **Developer guide** ([developer-guide/README.md](../developer-guide/README.md)) — practical instructions for scripts, **`ctx`**, kernel **`start(ctx)`**, coreutils development, testing, Pear integration, telemetry scrubbing.
4. **Reference** ([docs/reference/README.md](../docs/reference/README.md)) — inventory of packages and files, environment variable appendix, architecture data-flow notes, compatibility matrix, capability index.
| Tree | Role |
| --- | --- |
| **User manual** ([README](README.md)) | Run and use Bare OS without reading the whole architecture first. |
| **Handbook** ([../handbook/README.md](../handbook/README.md)) | Narrative design, protocol, runtime, identity, POSIX surface, operations, research. |
| **Developer guide** ([../developer-guide/README.md](../developer-guide/README.md)) | Scripts, **`ctx`**, **`start(ctx)`**, coreutils, testing, Pear, telemetry. |
| **Reference** ([../docs/reference/README.md](../docs/reference/README.md)) | Packages, env appendix, data flow, compatibility matrix, capabilities. |
If you are lost, start at the [documentation hub](../docs/README.md) on the **`docs/`** tree, which links outward to the handbook and developer guide.
If you are lost, start at the **[documentation home](../docs/README.md)**, which lists every tree plus **[glossary](../docs/glossary.md)**, **[FAQ](../docs/faq.md)**, **[troubleshooting router](../docs/troubleshooting.md)**, and **[contributing to docs](../docs/CONTRIBUTING-DOCS.md)**.
---
users-manual/07-troubleshooting-and-operations.md
+3
View File
@@ -31,6 +31,9 @@ Start the seeder first, wait until it is advertising, then start the booter. For
**Symptom: boot reaches shell but `/proc` looks empty or wrong.** Some **`/proc`** nodes require a minimum **ctx API** or capability words. Compare **`/proc/bare_os_features`** (when present) with the [compatibility matrix](../docs/reference/compatibility-matrix.md) and the versions printed by **`bare_os.capabilities`** during seeding.
> **Tip**
> For a symptom-first index into these docs, open [docs/troubleshooting.md](../docs/troubleshooting.md).
---
## Missing binaries or stale image
users-manual/08-further-reading.md
+10 -1
View File
@@ -6,6 +6,7 @@
## On this page
- [Documentation hubs](#documentation-hubs)
- [Architecture and protocol](#architecture-and-protocol)
- [Booter runtime and kernel](#booter-runtime-and-kernel)
- [Extending the system](#extending-the-system)
@@ -15,6 +16,14 @@
---
## Documentation hubs
- [docs/README.md](../docs/README.md) — full map of all trees, glossary, FAQ, troubleshooting, contributing to docs.
- [docs/glossary.md](../docs/glossary.md) — canonical terminology.
- [docs/faq.md](../docs/faq.md) — cross-cutting questions.
---
## Architecture and protocol
- [Handbook — Preface](../handbook/00-preface.md) — thesis, security limits, contributor paths.
@@ -46,7 +55,7 @@
- [Naming alias matrix](../docs/reference/naming-alias-matrix.md) — legacy ↔ canonical boot hooks and policy keys.
- [Naming migrations](../developer-guide/naming-migrations.md) — deprecation windows for renamed symbols.
- [Capability words](../docs/reference/capability-words.md) — wire layout for **`kernelCapabilityWords`**.
- [Feature roadmap](../docs/reference/feature-roadmap.md) — integration waves and mega-kernel checklists.
- [Feature roadmap](../docs/reference/feature-roadmap.md) — kernel program batches, capability-word checklists, integration status tables.
- [Environment and POSIX appendix](../docs/reference/environment-and-posix-appendix.md) — exhaustive **`BARE_OS_*`** list and POSIX notes.
- [packages/bare-os-booter/CHANGELOG.md](../packages/bare-os-booter/CHANGELOG.md) — **`bareOsCtxApiVersion`** history.
users-manual/README.md
+5 -14
View File
@@ -4,6 +4,9 @@ This manual is for **people who want to run and use** Bare OS: clone the repo, s
Bare OS is **experimental research software**, not a production operating system. It is licensed under **Apache-2.0** ([LICENSE](../LICENSE)).
> **Tip**
> If a term is unfamiliar, check the canonical **[glossary](../docs/glossary.md)** first, then jump back here.
---
## On this page
@@ -34,7 +37,7 @@ If you are **changing** `/bin`, the booter, or the kernel image, use the [develo
**I use it regularly.** Add [Shell, PATH, and scripts](04-shell-path-and-scripts.md), [Home, identity, and vault](05-home-identity-and-vault.md), and [Help, man, and the documentation map](06-help-man-and-documentation-map.md).
**I need to debug or operate it.** Use [Troubleshooting and operations](07-troubleshooting-and-operations.md) and the handbook chapter on operations ([Chapter 7 — Operations and development](../handbook/07-operations-and-development.md)).
**I need to debug or operate it.** Use [Troubleshooting and operations](07-troubleshooting-and-operations.md), the [docs troubleshooting router](../docs/troubleshooting.md), and the handbook chapter on operations ([Chapter 7 — Operations and development](../handbook/07-operations-and-development.md)).
---
@@ -55,6 +58,7 @@ If you are **changing** `/bin`, the booter, or the kernel image, use the [develo
- **[Handbook](../handbook/README.md)** tells the **story**: architecture, protocol, booter runtime, identity, POSIX surface, and roadmap. Start with the [Preface](../handbook/00-preface.md) if you want the full narrative.
- **[Developer guide](../developer-guide/README.md)** explains **how to build and extend** software on the image: `run(ctx, argv)`, coreutils, testing, Pear integration.
- **[docs/README.md](../docs/README.md)** is the **documentation home**: maps every tree, glossary, FAQ, troubleshooting router, ADRs, and release checklist.
- **[docs/reference](../docs/reference/README.md)** is the **file-level reference**: packages, environment variables, data flow, compatibility. Use it when you need exact paths or toggles.
- **[PEAR-RUN.md](../PEAR-RUN.md)** lists **Pear channels**, versioned `pear://` links, and host environment notes for embedded Pear apps.
@@ -62,19 +66,6 @@ When this manual and another doc disagree on a detail, treat the **handbook** or
---
## Quick glossary
These terms appear everywhere in the other trees; definitions here are **practical**, not formal specs.
- **Hyperdrive** — Content-addressed append-only log exposed as a familiar file tree; Bare OS stages the **system** image on one drive and keeps **personal** state on another.
- **Seeder** — Process that publishes the system drive (and MBR) to Hyperswarm so peers can replicate.
- **Booter** — Process that joins the swarm, opens drives, builds the guest VFS, and runs **`/boot/init.js`**.
- **MBR** — Small bootstrap block on the system drive that records discovery keys and version hints for the protocol; not a PC BIOS MBR.
- **Guest** — Unauthenticated session: safe default **`HOME`**, no Ed25519 identity in the environment.
- **`ctx`** — The in-image capability object (VFS, env, subprocess helpers, optional Pear bridges). User manual mentions it lightly; the [developer guide](../developer-guide/02-the-context-object.md) is the full map.
---
## Validating what you read
Repository **CI** runs **`npm run pretest`** before tests: it checks kernel/seeder parity, capability contracts, **relative `.md` links** under `docs/`, `handbook/`, `developer-guide/`, `scripts/`, `users-manual/`, `packages/`, `kernel/`, and root **`README.md`**, **`DOCUMENTATION.md`**, **`PEAR-RUN.md`**, **`man` coverage**, compatibility-matrix strings, and more. The link checker **skips** **`packages/bare-os-seeder/kernel/**`** (a byte-identical copy of **`kernel/**`**) and the **`packages/bare-os-bare-libs/README.kernel-lib-bare.md`** template whose links are validated after copy into **`kernel/lib/bare/README.md`**. If you are about to trust a path or script name from the docs, grepping the repo or running **`pretest`** locally is the fastest sanity check.