Attempt at beginning a ralph agent

docs/audit/PLACEHOLDER_BASELINE.md

@@ -33,7 +33,7 @@ This document classifies incomplete surfaces as of the kernel hardening pass. It
 | Item                         | Location                    | Notes |
 | ---------------------------- | --------------------------- | ----- |
 | ~~`gen-ctx-client-stub.mjs`~~ → **`gen-ctx-client-helper.mjs`** | `scripts/` | Renamed; generates TS client version constant aligned with **`BARE_OS_CTX_API_VERSION`**. |
-| Man / reference “placeholder” prose | `docs/`, `kernel/share/man/` | **Closed for stock tree:** `node scripts/verify-man-coverage.mjs` gates **155** Tier-1 commands ( **`COREUTILS_COMMANDS`** in **`packages/bare-os-coreutils/lib/commands.mjs`** ); regenerate merged man DB with **`npm run build -w bare-os-coreutils`** and **`npm run build -w bare-os-openssh`** when pages change. Narrative alignment: [handbook ch.9 §5](../../handbook/09-posix-utilities-shell-and-vfs.md#5-bin-utilities-catalog). |
+| Man / reference “placeholder” prose | `docs/`, `kernel/share/man/` | **Closed for stock tree:** `node scripts/verify-man-coverage.mjs` gates **157** Tier-1 commands ( **`COREUTILS_COMMANDS`** in **`packages/bare-os-coreutils/lib/commands.mjs`** ); regenerate merged man DB with **`npm run build -w bare-os-coreutils`** and **`npm run build -w bare-os-openssh`** when pages change. Narrative alignment: [handbook ch.9 §5](../../handbook/09-posix-utilities-shell-and-vfs.md#5-bin-utilities-catalog). |
 
 ## Extension multisig gate (stock kernel)
 

docs/get-started.md

@@ -26,7 +26,7 @@
 
 ## What you will have when this works
 
-- A **line shell** backed by **155** Tier-1 utilities under `/bin` (see [`packages/bare-os-coreutils/lib/commands.mjs`](../packages/bare-os-coreutils/lib/commands.mjs); **`sshd`** is built by **`bare-os-openssh`**).
+- A **line shell** backed by **157** Tier-1 utilities under `/bin` (see [`packages/bare-os-coreutils/lib/commands.mjs`](../packages/bare-os-coreutils/lib/commands.mjs); **`sshd`** is built by **`bare-os-openssh`**).
 - Two **Hyperdrives** mounted into one VFS: a **read-mostly system** image replicated from peers, and a **writable personal** drive for `$HOME`, `/.bare`, and similar paths. Short explainer: [Concepts — Two-drive model](concepts/two-drive-model.md).
 - A running **`/boot/init.js`** “kernel” and host-built **`ctx`** — not a hardware OS. See [User manual — Chapter 1](../users-manual/01-what-this-is.md).
 

docs/reference/environment-and-posix-appendix.md

@@ -304,7 +304,7 @@ The list below is one **bullet per variable** in the form **name — component
 - **Errno vocabulary** — **`/proc/bare_os/syscalls.json`** **`errnoHints`** and **`errnoAlignment`** document Linux-style integers (same family as **libuv** / **Holepunch `bare-fs`** binding **`error.code`** strings). Utilities such as **`mkdir`** print **`errno: message`** on stderr when the caught error exposes a string **`code`** (for example **`EEXIST`**, **`EACCES`**), matching the vocabulary in **`errnoHints`**. Simulated logical FDs (**`BARE_OS_POSIX_FD_SIM`**) use **`EBADF`**, **`EAGAIN`**, **`EINVAL`**, **`ENOSYS`**, **`EOPNOTSUPP`** consistently; **`fcntl`** cooperative **`F_SETLK`** returns **`EAGAIN`** when contended; **`F_SETLKW`** does the same unless **`BARE_OS_POSIX_FCNTL_BLOCKING_WAIT`** is set (then **`ETIMEDOUT`** when **`BARE_OS_FCNTL_LOCK_WAIT_MS_MAX`** elapses). Cooperative waits are **not** kernel futexes: callers may see an **`EINTR`-shaped note** when a blocking wait is interrupted by policy rather than a real signal. **`fcntl`** **`O_APPEND`**/**`O_NONBLOCK`** bit masks align with **`bare-fs`** open-flag shapes when the host resolves native FS errors.
 - **Shell** — Pipelines, **`;`**, **`&&`** / \*\*` —  — `**, redirects, quoting, **`$VAR`**, **`$?`**, optional **`${VAR:-word}`** / **`${VAR#prefix}`** when **`BARE*OS_SHELL_PARAM_EXPANSION=1`**, **`jobs`** / **`fg`** / **`wait`**, optional background **`&`** segments, builtins including bounded **`if`**, **`while`**, **`for`**, **`case`** (caps **`BARE_OS_SHELL_LOOP_MAX`**, **`BARE_OS_SHELL_CASE_MAX_BRANCHES`**). Optional bounded **`$(…)`** when **`BARE_OS_SHELL_CMDSUBST=1`**; optional larger pipeline capture via **`BARE_OS_SHELL_STREAMING`** / **`BARE_OS_SHELL_STREAMING_MULT`**. Branching uses **`ctx.exitCode`**. Bounded pipeline capture (**`BARE_OS_PIPELINE*\*`**, **`ctx.bareOsRuntimeCaps`**); optional boot-snippet allowlist (**`BARE_OS_BOOT_ALLOWLIST`** + **`/etc/bare-os/boot.allow`**). No subshells or full POSIX **`sh`\*\*.
 - **Ownership** — Display and permission checks use **`UID`/`GID`** and mode bits; **`chown`/`chgrp`** update **`metadata.bareOs`** on the **personal** writable tree (not a multi-user host kernel).
-- **Utilities** — Tier-1 JS **`/bin`** (**155** commands; authoritative list **`COREUTILS_COMMANDS`** in **`packages/bare-os-coreutils/lib/commands.mjs`**; **`sshd`**/**`bare-sshd`** binaries come from **`bare-os-openssh`**; see [§12.10](package-bare-os-coreutils-and-ci.md#1210-package-bare-os-coreutils)): text tools include **`paste`**, **`split`**, **`tac`**, **`rev`**, **`expand`**, **`unexpand`**, **`fold`**, **`fmt`**, **`comm`**, **`cmp`**, **`join`**, **`pr`**, **`yes`** (line-capped via **`BARE_OS_YES_MAX_LINES`** / **`getconf`**), **`shuf`** (capped via **`BARE_OS_SHUF_MAX_LINES`**), **`tsort`**, **`factor`**, **`expr`** (integer-focused subset), **`numfmt`** (**`--to=iec`** / **`--to=si`**). Checksums: **`md5sum`** (bundled MD5), **`sha1sum`**, **`sha224sum`** (bundled SHA-224), **`sha256sum`**, **`sha384sum`**, **`sha512sum`** (Web Crypto where available), **`sum`**, **`base32`**, **`basenc`** (**`--base16`**). Files: **`truncate`**, **`unlink`**, **`install`**, **`df`** (synthetic Hyperdrive row; **`-h`** human sizes), **`sync`** (no-op), **`timeout`** (wall-clock cap; exit **124** on timeout when **`BARE_OS_FEATURE_ABORT_TIMEOUT`** is advertised). Session stubs: **`arch`**, **`groups`**, **`hostid`**, **`nproc`**, **`uptime`**, **`users`**, **`who`**. Plus earlier parity: **`man`**, **`sed`** (including **`-z`**, **`BARE_OS_SED_NULL_MAX_RECORDS`**), **`awk`**, **`grep`** (**`-r`** with **`--include`/`--exclude`/`--exclude-dir`**, **`BARE_OS_GREP_FILTER_MAX`**), **`cp`** (**`-u`/`-v`/`-p`**), **`mv`**, **`find`** (**`-regex`**, **`-exec`/`-ok`**, **`BARE_OS_FIND_EXEC_MAX`**), **`mktemp`**, **`git-pear`**, **`cksum`**, **`getconf`** (static name table plus live **`vfs.env`** overrides for caps; **`-a`**), **`xargs`** (**`-P`** cap raised via **`BARE_OS_XARGS_MAX_PROCS`**, hard max **32**), **`getfacl`** / **`setfacl`** (POSIX-style ACL **view/edit** against synthetic **`/.bare_acl.json`** sidecars; see handbook ch.9), **`dircolors`**, **`theme`**, **`ls`**, **`uniq`**, **`realpath`**, **`base64`**, **`rm`** **`-d`**, **`stat`** **`%F`**. **`dir`** / **`vdir`** call **`ls`**. Large **`sed`/`awk`** are not byte-identical to GNU on all inputs. **`mkfifo`** → **`/run/bare-os/ipc/`**; optional logical process groups via **`ctx.bareOsIpc.assignProcessGroup`** / **`signalProcessGroup`** (POSIX **`setpgid`** / **`killpg`** analog for IPC routing). Machine-readable per-command POSIX hints: stock **`/etc/bare-os/posix_utilities.json`** (path echoed in **`/proc/bare_os_features`** and **`metrics_live`**). Online help: **`/share/man/man.json`** and **`man`**.
+- **Utilities** — Tier-1 JS **`/bin`** (**157** commands; authoritative list **`COREUTILS_COMMANDS`** in **`packages/bare-os-coreutils/lib/commands.mjs`**; **`sshd`**/**`bare-sshd`** binaries come from **`bare-os-openssh`**; see [§12.10](package-bare-os-coreutils-and-ci.md#1210-package-bare-os-coreutils)): text tools include **`paste`**, **`split`**, **`tac`**, **`rev`**, **`expand`**, **`unexpand`**, **`fold`**, **`fmt`**, **`comm`**, **`cmp`**, **`join`**, **`pr`**, **`yes`** (line-capped via **`BARE_OS_YES_MAX_LINES`** / **`getconf`**), **`shuf`** (capped via **`BARE_OS_SHUF_MAX_LINES`**), **`tsort`**, **`factor`**, **`expr`** (integer-focused subset), **`numfmt`** (**`--to=iec`** / **`--to=si`**). Checksums: **`md5sum`** (bundled MD5), **`sha1sum`**, **`sha224sum`** (bundled SHA-224), **`sha256sum`**, **`sha384sum`**, **`sha512sum`** (Web Crypto where available), **`sum`**, **`base32`**, **`basenc`** (**`--base16`**). Files: **`truncate`**, **`unlink`**, **`install`**, **`df`** (synthetic Hyperdrive row; **`-h`** human sizes), **`sync`** (no-op), **`timeout`** (wall-clock cap; exit **124** on timeout when **`BARE_OS_FEATURE_ABORT_TIMEOUT`** is advertised). Session stubs: **`arch`**, **`groups`**, **`hostid`**, **`nproc`**, **`uptime`**, **`users`**, **`who`**. Plus earlier parity: **`man`**, **`sed`** (including **`-z`**, **`BARE_OS_SED_NULL_MAX_RECORDS`**), **`awk`**, **`grep`** (**`-r`** with **`--include`/`--exclude`/`--exclude-dir`**, **`BARE_OS_GREP_FILTER_MAX`**), **`cp`** (**`-u`/`-v`/`-p`**), **`mv`**, **`find`** (**`-regex`**, **`-exec`/`-ok`**, **`BARE_OS_FIND_EXEC_MAX`**), **`mktemp`**, **`git-pear`**, **`cksum`**, **`getconf`** (static name table plus live **`vfs.env`** overrides for caps; **`-a`**), **`xargs`** (**`-P`** cap raised via **`BARE_OS_XARGS_MAX_PROCS`**, hard max **32**), **`getfacl`** / **`setfacl`** (POSIX-style ACL **view/edit** against synthetic **`/.bare_acl.json`** sidecars; see handbook ch.9), **`dircolors`**, **`theme`**, **`ls`**, **`uniq`**, **`realpath`**, **`base64`**, **`rm`** **`-d`**, **`stat`** **`%F`**. **`dir`** / **`vdir`** call **`ls`**. Large **`sed`/`awk`** are not byte-identical to GNU on all inputs. **`mkfifo`** → **`/run/bare-os/ipc/`**; optional logical process groups via **`ctx.bareOsIpc.assignProcessGroup`** / **`signalProcessGroup`** (POSIX **`setpgid`** / **`killpg`** analog for IPC routing). Machine-readable per-command POSIX hints: stock **`/etc/bare-os/posix_utilities.json`** (path echoed in **`/proc/bare_os_features`** and **`metrics_live`**). Online help: **`/share/man/man.json`** and **`man`**.
 - **Process tooling note** — **`ps`** and **`kill`** operate on Bare OS synthetic process rows (`pid` 1..3 for kernel/booter/shell); they do not target host OS processes.
 - **Additional utility coverage** — **`dd`** (block-copy subset) and **`logger`** (structured append to **`/var/log/messages`**) are available as Tier-1 commands.
 - **Mount tooling note** — **`mount`** / **`umount`** are Hyperdrive/HDMS-backed commands for `/mnt/<label>` and are not host-kernel mount syscalls.