Docs+handbook

kernel/README.md

@@ -0,0 +1,31 @@
+# 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.
+
+## Staging map (seeder)
+
+| Source         | Drive path         |
+| -------------- | ------------------ |
+| `init.js`      | `/boot/init.js`    |
+| `bin/<name>`   | `/bin/<name>`      |
+| `etc/...`      | `/etc/...`         |
+| Any other file | `/<relative path>` |
+
+## Contents
+
+- **`init.js`** — Kernel entry: must define `async function start(ctx)`. Reads `/etc/os-release`, prints a short banner, loops on `readLine` / `execLine` (with error handling so user mistakes do not tear down the session).
+- **`bin/`** — **Tier-1 utilities** built by [bare-os-coreutils](../packages/bare-os-coreutils/README.md). Each file is `runtime.js` + `async function run(ctx, argv)`.
+- **`etc/os-release`** — Static OS metadata (`NAME`, `VERSION`, …).
+
+## Editing workflow
+
+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 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`.
+
+## See also
+
+- [Handbook — Kernel and userspace](../handbook/06-kernel-and-binaries.md)
+- [DOCUMENTATION.md](../DOCUMENTATION.md) §9