Welcome. This handbook is the narrative companion to the repo: it explains why the pieces exist, how they connect, and what to run when things go wrong. For an exhaustive file-by-file inventory, keep DOCUMENTATION.md open alongside—it is the closest thing to a generated map of every source path.

This project is experimental research software: a distributed system image living in Hyperdrive, discovered over Hyperswarm, executed by Bare/Pear apps. It is not a production OS.

Who this is for

You want a mental model of seeder vs booter vs kernel vs /bin.
You need diagrams of data flow and trust boundaries.
You are extending coreutils, VFS, identity, HDMS, or initd services.

Reading order

Chapter	Topic
01 — Introduction	Goals, vocabulary, Holepunch stack
02 — Blueprints	Layered architecture, trust, diagrams
03 — Protocol and disk	MBR, swarm, Protomux, SwarmDisk
04 — The booter runtime	`ctx`, VFS, shell, kernel runner, initd, cron, REPL
05 — Identity, vault, HDMS	Guest vs user, `/.bare/account`, extra drives
06 — Kernel and binaries	`/boot/init.js`, coreutils catalog
07 — Operations and development	Env vars, npm scripts, CI, Pear, troubleshooting

Package READMEs (quick links)

Root README

The top-level README.md is the short runbook (install, test, pear run, guest identity). Start there if you only need commands.

License: Apache-2.0 — see LICENSE.