bare-operating-system/packages/bare-os-seeder/kernel/README.md

# 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/) (**188** 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/engines/md5.js`** for **`md5sum`**, **`lib/engines/sha224.js`** for **`sha224sum`**, **`lib/engines/*-engine.js`** for **`sed`**/**`awk`**, **`jq-engine.js`**, **`lib/engines/man-render.js`**, **`lib/edit/`** 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/ctx/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