docs updates

2026-04-04 08:31:39 -04:00
parent 0e53351349
commit 081e4c587c
64 changed files with 2052 additions and 1273 deletions
@@ -0,0 +1,59 @@
+# Chapter 1 — What this is
+
+**Audience:** anyone new to Bare OS. **Time to read:** about five minutes.
+
+---
+
+## On this page
+
+- [The idea in one paragraph](#the-idea-in-one-paragraph)
+- [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)
+- [Experimental software](#experimental-software)
+
+---
+
+## The idea in one paragraph
+
+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.
+
+---
+
+## 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.
+
+The **personal drive** is **yours** for that node: guest and user home layouts under controlled prefixes, account material under **`/.bare/`**, vault snapshots, HDMS registry data, and similar. The virtual file system **routes** paths such as **`$HOME`** and parts of **`/.bare/`** to this drive so the two namespaces feel like one tree.
+
+For the protocol layout (MBR, keys, swarm topic names), read [Handbook — Chapter 3: Protocol and disk](../handbook/03-protocol-and-disk.md).
+
+---
+
+## How you get the image
+
+In development you typically:
+
+1. Clone the **git repository** and run **`npm ci`** at the root.
+2. Run a **seeder** that stages **`kernel/`** into the system Hyperdrive and advertises it on the network.
+3. Run a **booter** in another process that discovers peers and boots into the image.
+
+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.
+
+---
+
+## What you can do inside
+
+Stock images ship a **line-oriented shell** with pipelines and redirects, a large set of **POSIX-style utilities** under **`/bin`**, **`sed`** and **`awk`**, and **`man`** backed by merged handbook and coreutils pages. **Identity** starts as **guest**; **`login`** can unlock an Ed25519-backed account on the personal drive. Optional **HDMS** can attach more Hyperdrives under **`/mnt`**.
+
+The exact surface and intentional POSIX gaps are summarized in [Handbook — Chapter 9](../handbook/09-posix-utilities-shell-and-vfs.md).
+
+---
+
+## Experimental software
+
+Bare OS is **not** a production operating system. APIs, disk formats, and network behavior can change. Use it for research, prototyping, and learning. For security and trust boundaries, read [Handbook — Preface](../handbook/00-preface.md) and [Developer guide — Security and trust](../developer-guide/09-security-and-trust.md).
+
+---
+
+_Previous: [User manual home](README.md)_ · _Next: [Chapter 2 — Install and repository layout](02-install-and-repository-layout.md)_