updates

DOCUMENTATION.md

@@ -275,7 +275,7 @@ Pear-safe path resolution (same idea as Holepunch [pear-rti](https://github.com/
 **`main()`**
 
 1. Optional `console.clear()`.
-2. Dynamic import of `../bare-os-coreutils/build.mjs` and `await build()` (emit `/bin` scripts into `kernel/` and seeder copy).
+2. **`maybeBuildCoreutilsFromSource()`** — only when `import.meta.url` starts with `file:` (Node / `node index.js`): dynamic import of `../bare-os-coreutils/build.mjs` and `await build()`. Under **Pear** (`pear://` URLs) this is skipped; the bundle must include an up-to-date vendored `kernel/` (run `npm run build -w bare-os-coreutils` before `pear run`).
 3. `Corestore(corestorePath())`, `Hyperdrive(store)`, `ready()`.
 4. `stageKernelTree`.
 5. `localRAM = Map`, `buildMbr(drive.key)`, `localRAM.set(0, mbr)`.
@@ -320,7 +320,7 @@ Pear-safe path resolution (same idea as Holepunch [pear-rti](https://github.com/
 
 **`executeKernel(disk, store, swarm, initSource)`** (`store`/`swarm` unused but kept for signature symmetry / future use)
 
-- Builds `shellEnv` (`HOME`, `PATH=/bin`, `USER`, `PWD`, `SHELL`, `0`) and `createVfs(drive, personalDrive, shellEnv)` → `ctx.vfs` (same `env` object as `ctx.env`).
+- Builds `shellEnv` (`HOME`, `PATH=/bin`, `USER`, `PWD`, `SHELL`, `HOSTNAME`, `UID`/`GID`/`GROUP`, `0`) and `createVfs(drive, personalDrive, shellEnv)` → `ctx.vfs` (same `env` object as `ctx.env`).
 - Builds `ctx`: `disk`, `drive`, `personalDrive`, `vfs`, `env`, `console`, `b4a`, `topic: topicKey()`, `readLine`, `execLine` → `execShellLine(ctx, line)` (returns `'ok'` or `'exit'`).
 - Sets `disk.os` with stub `searchLocal` ([]) and `execRpc` (`''`).
 - `runKernelFromSource(b4a.toString(initSource), ctx)`.
@@ -392,6 +392,7 @@ Pear-safe path resolution (same idea as Holepunch [pear-rti](https://github.com/
 - **Logical paths** under `$HOME` (default `/home/user`) map to the **personal** Hyperdrive; all other absolute paths use the **system** drive (read-mostly OS image).
 - **`resolveLogical(p)`** — `unix-path-resolve(cwd, p)` so cwd + relative segments work (the `unix-path-resolve` package only accepts two path arguments).
 - **API**: `getcwd`, `chdir` (rejects regular files), `readFile`, `writeFile` / `unlink` (personal only), `exists`, `readdir`, `stat` (file vs directory via entry + shallow children).
+- **Hyperdrive quirk**: `entry` / `get` / `exists` use `std(path, false)` and **throw** on path `'/'` (`Invalid filename: /`). The VFS special-cases drive path `'/'` (logical `/` and personal `$HOME` root) for `chdir`, `stat`, `exists`, `isRegularFile`, and blocks `readFile`/`put`/`del` on that key.
 
 ### 12.7 [packages/bare-os-booter/lib/shell.js](packages/bare-os-booter/lib/shell.js)
 
@@ -401,7 +402,7 @@ Pear-safe path resolution (same idea as Holepunch [pear-rti](https://github.com/
 ### 12.8 Package `bare-os-coreutils`
 
 - **[packages/bare-os-coreutils/build.mjs](packages/bare-os-coreutils/build.mjs)** — `export async function build()`: concatenates `lib/runtime.js` + each `src/<name>.js`, writes to `kernel/bin/<name>` and `packages/bare-os-seeder/kernel/bin/<name>`. CLI: `node build.mjs` when executed as main.
-- **Tier-1 commands** (sources under `src/`): `ls`, `pwd`, `cat`, `test`, `basename`, `dirname`, `wc`, `head`, `tail`, `uname`, `pathchk`, `echo`, `help`. Scripts are plain `async function run(ctx, argv)` using `ctx.vfs`, `ctx.b4a`, `ctx.console`, optional `bareStdin(ctx)` — no ESM `import` (Bare-safe `AsyncFunction` load).
+- **Commands** (sources under `src/`, list in `build.mjs`): `basename`, `cat`, `clear`, `date`, `dirname`, `echo`, `env`, `false`, `head`, `help`, `hostname`, `id`, `ls`, `nl`, `pathchk`, `printenv`, `pwd`, `rm`, `seq`, `sleep`, `sort`, `tail`, `test`, `touch`, `true`, `tty`, `uname`, `wc`, `which`, `whoami`. Scripts are plain `async function run(ctx, argv)` using `ctx.vfs`, `ctx.drive`, `ctx.b4a`, `ctx.console`, optional `bareStdin(ctx)` — no ESM `import` (Bare-safe `AsyncFunction` load).
 
 ### 12.9 [packages/bare-os-booter/test.js](packages/bare-os-booter/test.js)
 
@@ -421,7 +422,7 @@ Uses Node builtins: `node:fs`, `node:path`, `node:url`.
 
 ### 12.10 Seeder: coreutils build hook
 
-- **[packages/bare-os-seeder/index.js](packages/bare-os-seeder/index.js)** — at start of `main()`, dynamic `import('../bare-os-coreutils/build.mjs')` then `await build()` so staging always picks up emitted `/bin` scripts.
+- **[packages/bare-os-seeder/index.js](packages/bare-os-seeder/index.js)** — when not on Pear (`import.meta.url` is `file:`), dynamic `import('../bare-os-coreutils/build.mjs')` then `await build()`. Pear has no sibling `bare-os-coreutils` in the bundle; use pre-built files under vendored `kernel/bin/`.
 
 ---