Updates

handbook/04-the-booter-runtime.md

@@ -46,7 +46,8 @@ Virtual listings include **`/home`** (session-specific) and **`/mnt`** when HDMS
 **`execShellLine`** (`lib/shell.js`):
 
 - Tokenizes words, quotes, escapes, **`$VAR`**, pipelines **`|`**, redirections **`>` / `>>` / `<`**.
-- Builtins: **`cd`**, **`export`**, **`login`**, **`logout`**, **`exit`** — plus external commands via **`runBinCommand`**.
+- Builtins: **`alias`**, **`unalias`**, **`cd`**, **`export`**, **`login`**, **`logout`**, **`exit`** — plus external commands via **`runBinCommand`**.
+- First-word **aliases** (defaults like **`ll` → `ls -la`**) expand after **`$VAR`** substitution; **`alias`** / **`unalias`** match the restricted **`~/.barerc`** syntax (not full POSIX **`sh`**).
 - Pipes capture **`console.log`** into the next stage or a string sink.
 
 **`runBinCommand`** (`lib/kernel-runner.js`):
@@ -59,6 +60,15 @@ Virtual listings include **`/home`** (session-specific) and **`/mnt`** when HDMS
 
 **`runKernelFromSource`** requires **`async function start(ctx)`** at the top level of `/boot/init.js`.
 
+### `~/.barerc` (restricted startup file)
+
+On **guest** and **logged-in** identity transitions, the booter loads **`~/.barerc`** from the personal drive if it exists. On **login** (unlocked identity), if the file is **missing**, the booter creates a **comment-only skeleton** you can edit. Only these forms are applied (other lines are ignored; set **`BARE_OS_STRICT_BARC=1`** to log warnings):
+
+- **`export NAME=value`** — same name rules as the shell builtin; value is expanded like **`export`** in **`execShellLine`**.
+- **`alias name=value`** and **`unalias`** — same behavior as the interactive builtins (**`unalias -a`** resets to the default alias table).
+
+There is no arbitrary command execution, **`source`**, or control flow — it is intentionally not a full **`sh`** profile.
+
 ---
 
 ## bare-initd and kernel logger

handbook/06-kernel-and-binaries.md

@@ -57,7 +57,7 @@ packages/bare-os-seeder/kernel/bin/<cmd>   ← Pear vendored copy
 | `ls`                             | Lists directories; **hides `.*` unless `-a`**                                                                           |
 | `pathchk`                        | Path sanity                                                                                                             |
 | `pwd`                            | Logical cwd                                                                                                             |
-| `rm`                             | Unlink files                                                                                                            |
+| `rm`                             | Remove files; **`-r`/`-R`/`--recursive`** for directories, **`-f`/`--force`** (bundled **`-rf`**) — uses VFS tree walk + `del` per entry |
 | `savevault`                      | Encrypted vault snapshot                                                                                                |
 | `seq`, `sleep`, `sort`           | Misc                                                                                                                    |
 | `test`, `[`                      | Conditionals (as implemented)                                                                                           |

handbook/08-git-on-bare-os.md

@@ -0,0 +1,19 @@
+# Git on Bare OS
+
+The `git` command in this project is **not** the GNU Git binary. It is a small CLI in the booter package that calls **[isomorphic-git](https://isomorphic-git.org/)** — a JavaScript implementation with a **fixed set of APIs**, not parity with every `git` subcommand you might know from a desktop Linux install.
+
+## How it runs
+
+- **Delegation:** When you type `git` (or an absolute path like `/bin/git` whose basename is `git`), the booter loads `git-cli.js` with a normal ESM `import`. That avoids the Hyperdrive `/bin` model, where utilities are concatenated and `eval`’d without `import`, which cannot load npm packages.
+- **Storage:** Repositories live on the **VFS** (personal drive under `$HOME`, or writable HDMS mounts). isomorphic-git expects a Node-style `fs.promises` surface; the booter provides **`createGitFsFromVfs`**, which maps those calls onto Hyperdrive-backed paths. Empty directories use a hidden marker file (`.bareos_empty`) because Hyperdrive does not always mirror POSIX directory semantics.
+
+## Network (clone, fetch, push)
+
+- On **Node**, HTTP defaults to **`isomorphic-git/http/node`** (`simple-get`).
+- If that fails to load, or when you set **`BARE_OS_GIT_HTTP=web`**, the CLI uses **`isomorphic-git/http/web`**, which expects a global **`fetch`**. Node 18+ and browsers already provide it; **Pear/Bare does not**, so the booter loads **`bare-fetch`** (Holepunch) and assigns **`globalThis.fetch`** (plus `Request` / `Response` / `Headers`) before using the web client.
+- TLS and network policy still depend on the host; some remotes may fail for certificate or connectivity reasons unrelated to isomorphic-git.
+
+## Expectations
+
+- Use **`git --help`** inside Bare OS for the supported subcommand list.
+- Unsupported subcommands print a short message; for full API behavior, see the [isomorphic-git documentation](https://isomorphic-git.org/docs/en/next/alphabetic).

handbook/README.md

@@ -25,6 +25,7 @@ This project is **experimental research software**: a distributed **system image
 | [05 — Identity, vault, HDMS](05-identity-vault-and-hdms.md)         | Guest vs user, `/.bare/account`, extra drives       |
 | [06 — Kernel and binaries](06-kernel-and-binaries.md)               | `/boot/init.js`, coreutils catalog                  |
 | [07 — Operations and development](07-operations-and-development.md) | Env vars, npm scripts, CI, Pear, troubleshooting    |
+| [08 — Git on Bare OS](08-git-on-bare-os.md)                         | isomorphic-git, VFS fs adapter, HTTP modes          |
 
 ---