# kernel — system image sources

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.

**This `README.md` file** only documents the tree layout in the repository; the seeder **does not** install it as `**/README.md`** on the image (so the guest root directory stays free of repo docs).

**Documentation:** [Concepts — Boot](../docs/concepts/boot-and-init-timeline.md) · [User manual](../users-manual/README.md) · [Handbook](../handbook/README.md) · [Kernel image reference](../docs/reference/kernel-image.md) · [Developer guide](../developer-guide/README.md).

## Staging map (seeder)

- `**init.js`** — `/boot/init.js`
- `**bin/<name>**` — `/bin/<name>`
- `**etc/...**` — `/etc/...`
- `**share/man/...**` — `/share/man/...`
- `**lib/bare/...**` — `/lib/bare/...` (optional `**ctx.bare**` bundles; see `**bare-os-bare-libs**`)
- **Any other file** — `/<relative path>`
- `**README.md` (this file)** — *(skipped — not copied to `/README.md`)*

## Contents

- `**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](../developer-guide/02-the-context-object.md)`).
- `**bin/**` — **Tier-1 utilities** built by [bare-os-coreutils](../packages/bare-os-coreutils/README.md) plus `**sshd`** / `**bare-sshd**` from [bare-os-openssh](../packages/bare-os-openssh/) (**153** commands in `**COREUTILS_COMMANDS`**; `**sshd**` is listed for man/help but its concatenated script is emitted by the openssh package build, not coreutils `**src/**`). Each file is `**runtime.js**` + optional preamble (`**lib/md5.js**` for `**md5sum**`, `**lib/sha224.js**` for `**sha224sum**`, `**lib/*-engine.js**` for `**sed**`/`**awk**`, `**jq-engine.js**`, `**lib/man-render.js**`, `**lib/edit-*.js**` for `**edit**`/`**nano**`, lscolors for `**ls**`/`**dircolors**`, …) + `**async function run(ctx, argv)**` (no ESM `**import**` in `**src/**`). `**/bin/nano**` duplicates `**/bin/edit**` for familiarity; the shell’s default `**nano` → `edit**` alias uses the `**edit**` command name after expansion. `**dir**`/`**vdir**` invoke `**ls**` via `**ctx.runBinCommand**`.
- `**lib/bare/**` — Optional IIFE bundles + `**manifest.json**` for `**ctx.bare**` drive merge, built by [bare-os-bare-libs](../packages/bare-os-bare-libs/README.md). Same trust model as `**bin/**` (trusted seeded image).
- `**share/man/man.json**` — Merged manual database for `**/bin/man**` (built by `**bare-os-coreutils**`; see [handbook ch.10](../handbook/10-manpages-and-online-help.md)).
- `**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](../developer-guide/02-the-context-object.md)).
- `**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

**Do not edit `kernel/init.js` by hand.** It is generated from `kernel/lib/boot/*.js` (sorted), `kernel/lib/init/fragments/*.js` (sorted), and `kernel/lib/init/init-main.js` via `npm run bundle:kernel` (`scripts/bundle-kernel-init.mjs`). CI and `npm run verify:init-bundle` fail when the file drifts. Edit the fragments under `lib/boot/`, `lib/init/fragments/`, and `lib/init/` only, then bundle and rsync to `packages/bare-os-seeder/kernel/` for Pear parity. See `lib/init/STRUCTURE.md`.

1. Change sources under `kernel/` or `packages/bare-os-coreutils/src/`.
2. Run `npm run build -w bare-os-coreutils` to refresh `kernel/bin/*`.
3. Run `npm run build -w bare-os-bare-libs` when `**packages/bare-os-booter/lib/bare-module-manifest.json`** or bundle entries change.
4. Run seeder again to re-stage the drive (or use a fresh Corestore for a clean image).

**Host boot perf:** when `**BARE_OS_BOOT_PERF_DETAIL=1`**, the stock booter logs `**bare_stdlib_merge_ns**` after `**maybeMergeBareFromDrive**` (monotonic `**hrtime**` delta in nanoseconds) alongside guest `**boot-perf.json**` stages.

Pear bundles use the **vendored** tree under `packages/bare-os-seeder/kernel/`; keep it in sync by running the same builds before `pear stage`. Use `**npm run maintainer:kernel-image`** from the repo root for coreutils + bare-libs + init bundle + extensions index + parity verify (then `**rsync -a --delete kernel/ packages/bare-os-seeder/kernel/**` if the verifier reports drift). `**npm test**` runs `**scripts/verify-kernel-seeder-parity.mjs**`, `**scripts/verify-ctx-api-feature-bits.mjs**`, and `**scripts/validate-example-schemas.mjs**` (after `**bare-os-coreutils**` and `**bare-os-bare-libs**` builds) so the two trees match byte-for-byte, ctx semver / feature words stay wired, example JSON matches `**[docs/schemas/](../docs/schemas/)**`, 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/boot.policy.example.json**` (install as `**boot.policy.json**` when using `**BARE_OS_BOOT_POLICY=1**`; v2 fields `**maxExecLineDepth**`, `**denyEnvKeys**`, `**requireProcNodes**`; v3 `**requireKernelCapabilitiesExtendedSeedingPlatform**`, `**requireKernelCapabilitiesRlimitsDelegatesShell**`, `**allowedPearIpcChannels**`, `**denyVfsPrefixes**`, `**maxInitdRestartsPerUnit**`; v4 `**requireKernelCapabilitiesOfflineNetExtensions**`, `**denyExecLineBuiltins**`, `**allowedCtxMethods**`; v9 `**requireKernelCapabilitiesBareModuleCryptoStaging**`, `**requirePearRuntimeRange**`, `**denyBareModuleSpecifierPatterns**`, `**requireBareCryptoMin**`, `**denyKernelSyscalls**`, `**requirePearIpcMin**`, `**extensionSignerPinsV2**`, `**offlineLkgManifestMaxAgeSec**`, `**bootPhasesRequireProcIndexMinSchema**`; v10 `**requireKernelCapabilitiesPearInspectLoggerTls**`, `**requireBareBootMin**`, `**bootPhasesRequireLifecycleMinSchema**`, `**extensionSignerPinsV3**`, …; JSON Schema: `[docs/schemas/boot.policy.schema.json](../docs/schemas/boot.policy.schema.json)`), `**etc/bare-os/kernel.extensions.registry.example.json**` (shape for `**/proc/bare_os/extensions.json**` schema 7), `**etc/bare-os/boot-trace-line.example.json**` and `**etc/bare-os/telemetry-ndjson.example.json**` (shape checks for CI), `**etc/bare-os/rc.profile.full**` (sample full profile referenced from `**profile**`), `**etc/bare-os/crontab.example**` (system-wide cron lines merged ahead of user `**~/.crontab**`), `**etc/bare-os/timers/*.timer.example**` (copy to `**~/.config/bare-os/timers/*.timer**` for `**OnCalendar=**`, `**EveryMs=**`, or `**OnInactiveSec=**` jobs). `**kernel.ext.d**` scripts register into `**/proc/bare_os/extensions.json**` when the booter provides `**ctx.bareOsRegisterKernelExtensionRecord**`.

## See also

- [Handbook — Kernel and userspace](../handbook/06-kernel-and-binaries.md)
- [Handbook — POSIX utilities, shell, VFS](../handbook/09-posix-utilities-shell-and-vfs.md)
- [Kernel image reference](../docs/reference/kernel-image.md) §9