Dev guide

handbook/10-manpages-and-online-help.md

@@ -19,6 +19,7 @@ Bare OS ships a **`man(1)`**-style viewer backed by a **JSON manual database** o
 | **1**   | User commands — every name in **`COREUTILS_COMMANDS`**, including **`man`** itself. |
 | **1**   | **`bare-os-shell`** — one manual for **all** interactive shell builtins (`cd`, `export`, …), so we do not maintain dozens of one-line stubs. |
 | **7**   | **Handbook** — every **`handbook/*.md`** file is merged at build time as **`man(7)`** (POSIX “miscellaneous”). TOC: **`man handbook`** or **`man 7 bare-os-handbook`** (alias **`handbook`**). Chapters: **`man handbook-01-introduction`**, **`man 7 handbook-02-blueprints`**, … **`mermaid`** diagrams are omitted in the terminal view; open the Markdown in the repo for figures. |
+| **7**   | **Developer guide** — every **`developer-guide/*.md`** file is merged the same way. TOC: **`man devguide`** or **`man 7 bare-os-developer-guide`** (aliases **`developer-guide`**, **`devguide`**). Chapters: **`man devguide-01-two-runtimes-host-vs-image`**, … |
 
 **`git`** is not a `/bin` script (it is delegated in the booter to **`git-cli.js`**), but it still has a **section 1** page **`git`** in the same database.
 
@@ -31,7 +32,7 @@ Bare OS ships a **`man(1)`**-style viewer backed by a **JSON manual database** o
 | `man` | Short usage and pointer to **`man -l`**. |
 | `man name` | Show manual for **`name`** (any section if the name is unique, e.g. **`man ls`** or **`man handbook`**). |
 | `man 1 name` / `man 7 name` | Require that section; fails if the page lives in another section (e.g. **`man 7 ls`** fails). |
-| `man -l` | List **`name(section)`** for every page, sorted by name. |
+| `man -l` | List every page under category headings (**`/bin`**, **git/shell**, **handbook**, **developer guide**), then **`name(section)`** alphabetically within each group. |
 | `man -k word` | Apropos: pages whose keywords / title / name match **`word`** (substring, case-insensitive). |
 | `man -f name` | Whatis: one-line **`name(section) - title`** for an exact **`name`** match. |
 

handbook/README.md

@@ -29,6 +29,8 @@ This project is **experimental research software**: a distributed **system image
 | [09 — POSIX utilities, shell, VFS](09-posix-utilities-shell-and-vfs.md) | XCU-style `/bin`, `sed`/`awk`, builtins, `mkdir`, stubs, divergence from Issue 7 |
 | [10 — Manual pages and online help](10-manpages-and-online-help.md)     | `man(1)`, `/share/man/man.json`, schema, build, relationship to `help`         |
 
+**Companion — developer guide** (how to write `run(ctx, argv)` / `start(ctx)`, extend `/bin`, testing): [developer-guide/README.md](../developer-guide/README.md).
+
 ---
 
 ## Package READMEs (quick links)