bare-operating-system/docs

Bare OS — documentation home

Bare OS is an experimental, P2P-first system image: the operating tree lives on a replicated Hyperdrive, distributed via Hyperswarm and Protomux, with a separate personal drive for identity and mutable state. This page is the navigation hub for every documentation tree in the repository.

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.

Architecture snapshot

End-to-end data path from swarm connection to guest syscalls (canonical overview; details in the handbook and kernel contract):

flowchart TB
  subgraph swarmLayer [P2P transport]
    HS[Hyperswarm topic]
    MUX[Protomux on encrypted stream]
    CH1["Channel bare-os-v1"]
    CH2["Optional bare-os-app-v1"]
  end
  subgraph booterHost [Pear or Node booter]
    DISK[SwarmDisk + Corestore]
    CTX["ctx: vfs IPC syscall swarm hooks"]
  end
  subgraph guestImage [Hyperdrive system image]
    INIT["/boot/init.js stock kernel"]
    BIN["/bin coreutils"]
  end
  HS --> MUX
  MUX --> CH1
  MUX --> CH2
  CH1 --> DISK
  DISK --> CTX
  INIT --> CTX
  BIN --> CTX

---

Maintainer quick path (build + parity)

When you change kernel/lib/init/, kernel/lib/boot/, kernel/lib/bare/, or kernel/bin/:

1. Run npm run build -w bare-os-coreutils and npm run build -w bare-os-bare-libs as needed.
2. Run npm run bundle:kernel (or full npm test, which bundles and verifies).
3. Keep packages/bare-os-seeder/kernel/ identical to kernel/ — scripts/verify-kernel-seeder-parity.mjs enforces this in pretest.

Details: scripts/README.md (maintainer build order), developer guide ch.7.

Choose your path

I want to…	Start here
Run the seeder and booter and use the shell	User manual
Understand architecture, protocol, and design intent	Handbook
Extend /bin, scripts, Pear apps, or ctx	Developer guide
Look up paths, env vars, wire formats, matrices	Reference hub
Define a term or compare version fields	Glossary · Compatibility matrix
Fix a problem quickly	Troubleshooting router · FAQ
Edit docs in this repo	Contributing to documentation

flowchart LR
  subgraph roles [By role]
    Run[Run and use]
    Think[Understand design]
    Build[Extend and ship]
    Spec[Specify and verify]
  end
  subgraph trees [Doc trees]
    UM[users-manual]
    HB[handbook]
    DG[developer-guide]
    RF[docs/reference + architecture]
  end
  Run --> UM
  Think --> HB
  Build --> DG
  Spec --> RF
  HB --> RF
  DG --> RF

---

Documentation map

User manual (users-manual/)

Practical, sequential guide for operators.

Chapter	Topic
README	Paths through the docs, how trees relate
01 — What this is	Two drives, P2P image, experimental status
02 — Install	Clone, npm ci, monorepo layout
03 — Seeder and booter	Node vs Pear, two terminals
04 — Shell and PATH	Commands and scripts without full ctx depth
05 — Home, identity, vault	Guest, login, vault snapshots
06 — Help and man	man, help, where each doc tree lives
07 — Troubleshooting	Common failures, env vars, CI
08 — Further reading	Curated deep links

Handbook (handbook/)

Narrative spine: why and how the system fits together.

Chapter	Topic
00 — Preface	Thesis, security frame, contributors
01 — Introduction	Goals, vocabulary, clone-to-prompt
02 — Blueprints	Layers, trust, boot path
03 — Protocol and disk	MBR, swarm, Protomux, failure modes
04 — Booter runtime	ctx, VFS, shell, bridges
05 — Identity, vault, HDMS	Accounts, vault, mounts
06 — Kernel and binaries	/boot/init.js, coreutils
07 — Operations	CI, Pear, env, troubleshooting
08 — Git on Bare OS	isomorphic-git, HTTP modes
09 — POSIX, shell, VFS	Coverage and divergences
10 — Man pages and help	JSON DB, handbook ingest
11 — Kernel program and research	Roadmap context, capability words

Developer guide (developer-guide/)

How-to for code inside and around the image.

Doc	Topic
01 — Two runtimes	Host vs in-image execution
02 — ctx	Capability object map
03 — Kernel boot	start(ctx)
04 — User scripts and PATH	run(ctx, argv)
05 — Modules	No ESM on drive
06 — Extending /bin	Coreutils pipeline
07 — Apps beyond shell	initd, cron, delegates
08 — Testing	npm test, Pear dev
09 — Security	Trust boundaries
10 — Glossary and FAQ	Dev-focused Q&A
11 — Pear cookbook	Pear integration patterns
12 — Bare modules	ctx.bare, manifests
13 — Privacy and telemetry	Scrub lists, PII posture
Extras	Phase alignment, kernel program, naming, node→Bare map, ADRs

Reference and contracts (this tree)

Resource	Purpose
Reference README	Topic index (packages, env, data flow)
KERNEL_CONTRACT	Booter vs image, boot steps, ctx API pointer
POSIX_DECLARED_PROFILE	Issue 7–like contract: shell, XCU, VFS, proc “syscall” models
kernel-subsystems	Subsystem boundaries
ADRs	Architecture decisions
Audit baseline	Incomplete surfaces (classified)
OTA and bundles	Release packaging notes
Release checklist	Pre-tag steps
Schemas	Boot policy, telemetry, extension manifests
Themes	Terminal theme packs
Machine-readable data	Roadmap JSON, terminology allowlist
Holepunch catalog	Optional ctx.bare bundle metadata

Contract bump checklist

When you change BARE_OS_CTX_API_VERSION, /proc JSON schemas, BARE_OS_PROTOCOL_* / package semver, BARE_OS_POSIX_PROFILE_VERSION, or kernel capability words, update every dependent artifact in one pass:

1. README.md and DOCUMENTATION.md if the version string or install story changes.
2. Handbook chapters touched by behavior (especially ch.3–4, 6, 9).
3. Users manual and Developer guide for operator or extension workflows.
4. docs/reference/compatibility-matrix.md and any affected topic pages under docs/reference/.
5. Package changelogs: packages/bare-os-booter/CHANGELOG.md, packages/bare-os-protocol/CHANGELOG.md when applicable.
6. docs/schemas/ and docs/architecture/POSIX_DECLARED_PROFILE.md when proc, telemetry, or POSIX profiles move.
7. kernel/etc/bare-os/syscalls.example.json and the seeder mirror after kernel contract edits; run node scripts/verify-kernel-seeder-parity.mjs.
8. Regenerate docs/reference/ctx-client-helper.generated.ts via root pretest ( gen-ctx-client-helper.mjs ).

---

Root stubs and Pear

• Legacy monolith map: DOCUMENTATION.md (points here and to reference).
• Pear channels and host env: PEAR-RUN.md.
• Repository quick start: README.md.

---

Contributing

Code and automation: scripts/README.md. Documentation style and verifiers: CONTRIBUTING-DOCS.md.