docs updates

2026-04-04 08:31:39 -04:00
parent 0e53351349
commit 081e4c587c
64 changed files with 2052 additions and 1273 deletions
@@ -2,7 +2,7 @@

 Welcome. This guide is the **how-to companion** for writing software **on** and **for** Bare OS: scripts that run inside the replicated system image, utilities under `/bin`, the session kernel, and—when you need full JavaScript modules—the **host** Pear packages that implement the booter and seeder.

-The [handbook](../handbook/README.md) explains _why_ the system is shaped the way it is (Hyperdrive, two drives, swarm boot). The [docs/reference](../docs/reference/README.md) inventory lists _where_ every file lives. **This guide** focuses on _what you actually type_: entrypoint signatures, the `ctx` object, why `import` does not work in drive-resident scripts, and how the coreutils build turns sources into `/bin` commands.
+The [handbook](../handbook/README.md) explains _why_ the system is shaped the way it is (Hyperdrive, two drives, swarm boot). The [docs/reference](../docs/reference/README.md) inventory lists _where_ every file lives. The [user manual](../users-manual/README.md) helps people **run** the system before they extend it. **This guide** focuses on _what you actually type_: entrypoint signatures, the `ctx` object, why `import` does not work in drive-resident scripts, and how the coreutils build turns sources into `/bin` commands.

 This project is **experimental research software**. APIs described here follow the current code in `packages/bare-os-booter` and `packages/bare-os-coreutils`; when in doubt, read the cited paths.

@@ -16,6 +16,14 @@ This project is **experimental research software**. APIs described here follow t

 ---

+## On this page
+
+- [Who this is for](#who-this-is-for)
+- [Reading order](#reading-order)
+- [Related docs](#related-docs)
+
+---
+
 ## Who this is for

 - You want to drop a **`hello.js`** on your personal drive and run it from the shell without misunderstanding the execution model.
@@ -27,29 +35,28 @@ This project is **experimental research software**. APIs described here follow t

 ## Reading order

-| Chapter                                                                 | Topic                                                                                      |
-| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| [01 — Two runtimes: host vs in-image](01-two-runtimes-host-vs-image.md) | Pear/Node packages vs Hyperdrive JS evaluated with `AsyncFunction`; trust boundaries       |
-| [02 — The context object (`ctx`)](02-the-context-object.md)             | `vfs`, `drive`, `console`, identity hooks, `execLine`, `runBinCommand`, …                  |
-| [03 — Kernel: `/boot/init.js`](03-kernel-boot-init.md)                  | `async function start(ctx)`; readline loop; calling the shell                              |
-| [04 — User scripts and PATH resolution](04-user-scripts-and-path.md)    | `run(ctx, argv)`, shebangs, `*.js` in cwd, `./` paths, `/bin`                              |
-| [05 — Modules and `import`](05-modules-and-imports.md)                  | Why ESM does not apply to in-image scripts; bundling and alternatives                      |
-| [06 — Extending `/bin` (coreutils)](06-extending-bin-coreutils.md)      | `commands.mjs`, `build.mjs`, preamble, man pages                                           |
-| [07 — Apps beyond the shell](07-apps-beyond-the-shell.md)               | What an “app” means here; initd, cron, git, custom kernels (overview)                      |
-| [08 — Testing and debugging](08-testing-and-debugging.md)               | `npm test`, Brittle, Pear dev, common failure modes                                        |
-| [09 — Security and trust](09-security-and-trust.md)                     | System vs personal drive; eval boundaries                                                  |
-| [10 — Glossary and FAQ](10-glossary-and-faq.md)                         | Quick definitions; frequent questions                                                      |
-| [11 — Kernel + Pear cookbook](11-kernel-pear-cookbook.md)               | Boot allowlist, timers, socket IPC, `vfs.watch`, HDMS hooks, Git-in-Pear, release metadata |
-| [12 — Bare modules and Pear ecosystem](12-bare-modules-and-pear-ecosystem.md) | `ctx.bare`, manifest, drive bundles, Holepunch `bare-*` mirror vs guaranteed keys |
-| [13 — Privacy, telemetry, and PII](13-privacy-telemetry-pii.md) | Scrub lists for NDJSON / OTel mirrors; non-secret posture |
-| [Node → Bare module map](node-to-bare-modules.md) | Guest-safe replacements for **`node:*`** built-ins (**`bare-crypto`**, **`bare-module`**, …) |
-| [bare-boot vs kernel phases](bare-boot-kernel-phase-alignment.md) | Conceptual map: Holepunch **`bare-boot`** stages vs stock **`kernel/init.js`** |
+- **[01 — Two runtimes: host vs in-image](01-two-runtimes-host-vs-image.md)** — Pear/Node packages vs Hyperdrive JS evaluated with `AsyncFunction`; trust boundaries.
+- **[02 — The context object (`ctx`)](02-the-context-object.md)** — `vfs`, `drive`, `console`, identity hooks, `execLine`, `runBinCommand`, …
+- **[03 — Kernel: `/boot/init.js`](03-kernel-boot-init.md)** — `async function start(ctx)`; readline loop; calling the shell.
+- **[04 — User scripts and PATH resolution](04-user-scripts-and-path.md)** — `run(ctx, argv)`, shebangs, `*.js` in cwd, `./` paths, `/bin`.
+- **[05 — Modules and `import`](05-modules-and-imports.md)** — Why ESM does not apply to in-image scripts; bundling and alternatives.
+- **[06 — Extending `/bin` (coreutils)](06-extending-bin-coreutils.md)** — `commands.mjs`, `build.mjs`, preamble, man pages.
+- **[07 — Apps beyond the shell](07-apps-beyond-the-shell.md)** — What an “app” means here; initd, cron, git, custom kernels (overview).
+- **[08 — Testing and debugging](08-testing-and-debugging.md)** — `npm test`, Brittle, Pear dev, common failure modes.
+- **[09 — Security and trust](09-security-and-trust.md)** — System vs personal drive; eval boundaries.
+- **[10 — Glossary and FAQ](10-glossary-and-faq.md)** — Quick definitions; frequent questions.
+- **[11 — Kernel + Pear cookbook](11-kernel-pear-cookbook.md)** — Boot allowlist, timers, socket IPC, `vfs.watch`, HDMS hooks, Git-in-Pear, release metadata.
+- **[12 — Bare modules and Pear ecosystem](12-bare-modules-and-pear-ecosystem.md)** — `ctx.bare`, manifest, drive bundles, Holepunch `bare-*` mirror vs guaranteed keys.
+- **[13 — Privacy, telemetry, and PII](13-privacy-telemetry-pii.md)** — Scrub lists for NDJSON / OTel mirrors; non-secret posture.
+- **[Node → Bare module map](node-to-bare-modules.md)** — Guest-safe replacements for **`node:*`** built-ins (**`bare-crypto`**, **`bare-module`**, …).
+- **[bare-boot vs kernel phases](bare-boot-kernel-phase-alignment.md)** — Conceptual map: Holepunch **`bare-boot`** stages vs stock **`kernel/init.js`**.

 ---

 ## Related docs

 - [Handbook home](../handbook/README.md)
+- [User manual](../users-manual/README.md)
 - [Chapter 4 — Booter runtime](../handbook/04-the-booter-runtime.md)
 - [Chapter 6 — Kernel and binaries](../handbook/06-kernel-and-binaries.md)
 - [Chapter 7 — Operations and development](../handbook/07-operations-and-development.md)