Welcome. This guide is the how-to companion for writing software on and for Bare OS: scripts that run inside the replicated system image, utilities under /bin, the session kernel, and—when you need full JavaScript modules—the host Pear packages that implement the booter and seeder.

The documentation home maps every tree plus the shared glossary, FAQ, troubleshooting router, and contributing to docs. The handbook explains why the system is shaped the way it is (Hyperdrive, two drives, swarm boot). The docs/reference inventory lists where every file lives. The user manual helps people run the system before they extend it. This guide focuses on what you actually type: entrypoint signatures, the ctx object, why import does not work in drive-resident scripts, and how the coreutils build turns sources into /bin commands.

This project is experimental research software. APIs described here follow the current code in packages/bare-os-booter and packages/bare-os-coreutils; when in doubt, read the cited paths.

ctx API versions: see packages/bare-os-booter/CHANGELOG.md for bareOsCtxApiVersion history and booter alignment. TypeScript-oriented authors can reference lib/bare-os-ctx.d.ts.

Feature-bit governance: ADR 001 — Kernel feature bit governance.

Capability map: docs/reference/kernel-capabilities-index.md.

Contract checks: changing bareOsCtxApiVersion or stock kernel feature bits should keep scripts/verify-ctx-api-feature-bits.mjs green (invoked from root pretest).

Architecture contract (boundaries): docs/architecture/KERNEL_CONTRACT.md — booter vs guest image, disk.os RPC, boot step IDs.

Kernel source set: docs/reference/kernel-extensions.md — first-party paths (kernel/init.js, kernel/lib/boot, built /bin) vs vendored kernel/lib/bare/bundles (Holepunch IIFEs), CI allowlists, and seeder parity. Hand-authored code must stay free of incomplete markers; bundles are gated by verify-bundle-markers.mjs, verify-bundle-throws.mjs ( new Error messages with not implemented / abstract-base-class semantics — see docs/audit/bundle-throw-allowlist.json), and sanitize-bare-bundles.mjs. Prefer shrinking the throw allowlist via upstream bundle refreshes over silent drift.

Local Holepunch mirror: run npm run audit:holepunch-clones to refresh docs/audit/holepunch-clone-sync-report.json (schema 2), holepunch-lockfile-drift.json, and NDJSON summaries. The sync report lists every bare-module-manifest.json entry against BARE_OS_HOLEPUNCH_CLONES_ROOT (default ~/dev/pearcli/holepunch-repos/holepunchto_repos): gitHead, originMainHead, commitsBehindOriginMain, commitsAheadOfOriginMain (meaningful after git fetch origin main in each clone). goldenPathRows mirrors goldenPathRepos in docs/audit/holepunch-drift-repos.json (Bare runtime + Pear + core wire stack) for quick maintainer diff review — it is not a CI gate. Root pretest runs verify-holepunch-clone-drift.mjs only against repos[] in the same JSON (empty = no-op). Maintainers may set BARE_OS_HOLEPUNCH_DRIFT_TIER1=1 to check tier1Repos[] instead (hypercore / hyperdrive / hyperswarm / protomux / pear / pear-runtime / bare-fs / bare-process). Regenerate the maximal npm catalog with node scripts/gen-bare-holepunch-catalog.mjs (or npm run gen:bare-catalog), then npm run sync:bare-manifest — see scripts/README.md.

Who this is for

You want to drop a hello.js on your personal drive and run it from the shell without misunderstanding the execution model.
You plan to add or change a /bin utility and need the no-import contract and build steps.
You are modifying the booter or seeder Pear apps and need to separate “host ESM” from “in-image AsyncFunction.”
You are debugging async function run(ctx, argv) or start(ctx) and need a map of ctx.

Maintainer cheat sheet (artifacts → verifiers)

What you touch	Responsibility	Root check
`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`	Emit `kernel/bin/*`, man merge	`npm run build -w bare-os-coreutils`
`kernel/lib/boot/`, `kernel/lib/init/`	Init bundle sources	`bundle-kernel-init.mjs`, `verify-init-bundle-recipe.mjs`
`kernel/` vs `packages/bare-os-seeder/kernel/`	Byte-identical mirror	`verify-kernel-seeder-parity.mjs`
`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`	Version table for releases	`verify-compat-matrix.mjs`, `verify-doc-contracts.mjs`
`docs/reference/posix-compliance-matrix.json`	POSIX profile linkage	`verify-posix-compliance-matrix.mjs`, `gen-posix-dashboard.mjs`

Full script index: scripts/README.md. Gate everything with npm run pretest before pushing doc or contract edits.

Reading order

01 — Two runtimes: host vs in-image — Pear/Node packages vs Hyperdrive JS evaluated with AsyncFunction; trust boundaries.
02 — The context object (ctx) — vfs, drive, console, identity hooks, execLine, runBinCommand, …
03 — Kernel: /boot/init.js — async function start(ctx); readline loop; calling the shell.
04 — User scripts and PATH resolution — run(ctx, argv), shebangs, *.js in cwd, ./ paths, /bin.
05 — Modules and import — Why ESM does not apply to in-image scripts; bundling and alternatives.
06 — Extending /bin (coreutils) — commands.mjs, build.mjs, preamble, man pages.
07 — Apps beyond the shell — What an “app” means here; initd, cron, git, custom kernels (overview).
08 — Testing and debugging — npm test, Brittle, Pear dev, common failure modes.
09 — Security and trust — System vs personal drive; eval boundaries.
10 — Glossary and FAQ — Quick definitions; frequent questions.
11 — Kernel + Pear cookbook — Boot allowlist, timers, socket IPC, vfs.watch, HDMS hooks, Git-in-Pear, release metadata.
12 — Bare modules and Pear ecosystem — ctx.bare, manifest, drive bundles, Holepunch bare-* mirror vs guaranteed keys.
13 — Privacy, telemetry, and PII — Scrub lists for NDJSON / OTel mirrors; non-secret posture.
Node → Bare module map — Guest-safe replacements for node:* built-ins (bare-crypto, bare-module, …).
bare-boot vs kernel phases — Conceptual map: Holepunch bare-boot stages vs stock kernel/init.js.
Kernel program (governed expansion) — Governance, boot hooks, /proc/bare_os/kernel_program.json, Bare stack pointers, 200-item roadmap batches.
Naming conventions — First-party vs vendored trees, ctx / env / proc naming.
Naming migrations — Legacy aliases and deprecation windows for boot hooks and policy keys.
Architecture decision records (ADRs) — Contract decisions and templates.
Kernel doctor / kernel-explain conventions — Structured diagnostic output.

License: Apache-2.0 — see LICENSE.

README.md

Bare OS — developer guide

On this page

Who this is for

Maintainer cheat sheet (artifacts → verifiers)

Reading order

Related docs