Files in this directory are read from disk by the seeder (or copied into packages/bare-os-seeder/kernel/ for Pear) and written into the system Hyperdrive with no temporary directory on the host.

Staging map (seeder)

Source	Drive path
`init.js`	`/boot/init.js`
`bin/<name>`	`/bin/<name>`
`etc/...`	`/etc/...`
`share/man/...`	`/share/man/...`
Any other file	`/<relative path>`

init.js — Kernel entry: must define async function start(ctx). Boot order: /etc/os-release → /etc/motd → optional /etc/bare-os/rc.profile.<profile> (profile from BARE_OS_BOOT_PROFILE or first line of /etc/bare-os/profile; the booter mirrors the resolved name in ctx.env.BARE_OS_BOOT_PROFILE_RESOLVED and /run/bare-os/boot_profile) → /etc/bare-os/rc → /etc/bare-os/rc.d/* (sorted; digit-prefixed names only; skip dotfiles, *~, README*, *.md; optional BARE_OS_RC_D_SKIP comma list and prefix* patterns) → optional /etc/bare-os/rc.local → /etc/bare-os/kernel.d/* (same rules as rc.d) → banner → when BARE_OS_SKIP_REPL, optional onboot lines from BARE_OS_ONBOOT or /etc/bare-os/onboot → readLine / execLine loop. Boot execLine errors in trusted snippets are logged; with BARE_OS_BOOT_STRICT=1 or true, the first throw calls requestBooterExit(1) and stops later boot phases. Custom kernels may call ctx.registerKernelShutdownHook(fn) before initd disposers; use ctx.bareOsRuntimeCaps for limits, pseudo paths, and features (developer-guide/02-the-context-object.md).
bin/ — Tier-1 utilities built by bare-os-coreutils. Each file is runtime.js + optional lib/*-engine.js (sed, awk) or lib/man-render.js (man) + async function run(ctx, argv) (no ESM import in src/).
share/man/man.json — Merged manual database for /bin/man (built by bare-os-coreutils; see handbook ch.10).
etc/os-release — Static OS metadata (NAME, VERSION, …).
etc/motd — Optional message printed after os-release (distributors can customize).
etc/bare-os/banner or /etc/issue — If present on the system drive, the default kernel prints one of these instead of the built-in session hint (unless BARE_OS_SKIP_REPL shortens the banner). Set BARE_OS_BOOT_TRACE=1 or true for [boot] phase: Nms lines on stderr, json for {"phase":"…","ms":n} per phase, or ndjson for machine-readable lines with sessionId. Recovery: BARE_OS_BOOT_MINIMAL, granular BARE_OS_BOOT_SKIP, optional BARE_OS_KERNEL_SELFTEST (TAP via BARE_OS_SELFTEST_FORMAT=tap; includes /proc/bare_os_resources / /proc/bare_os_features checks), readiness via ctx.bareOsPublishBootReady → /run/bare-os/ready and /run/bare-os/boot.json (phases from the stock kernel plus booterPhases from the booter — see developer guide ch.2).
etc/bare-os/rc — Optional boot snippet: one execLine per non-comment line (trusted).
etc/bare-os/rc.d/ — Optional extra snippets (basename must start with a digit), same line rules, run after rc in filename order. Human-oriented notes live in .README (a dotfile so legacy init.js never executes it).

Editing workflow

Change sources under kernel/ or packages/bare-os-coreutils/src/.
Run npm run build -w bare-os-coreutils to refresh kernel/bin/*.
Run seeder again to re-stage the drive (or use a fresh Corestore for a clean image).

Pear bundles use the vendored tree under packages/bare-os-seeder/kernel/; keep it in sync by running the same build before pear stage. npm test runs scripts/verify-kernel-seeder-parity.mjs (after bare-os-coreutils build) so the two trees match byte-for-byte and every kernel/bin/* file contains the BARE_OS_BIN_API pragma (coreutils runtime.js and hand-written stubs such as systemctl / journalctl).

Optional system image examples: etc/bare-os/boot.allow.example (copy to boot.allow when using host BARE_OS_BOOT_ALLOWLIST=1), etc/bare-os/crontab.example (system-wide cron lines merged ahead of user ~/.crontab).

README.md

kernel — system image sources

Staging map (seeder)

Contents

Editing workflow

See also