Docs Update

2026-04-04 19:51:05 -04:00
parent f8ddef7950
commit c29ec13cf9
47 changed files with 1106 additions and 464 deletions
@@ -0,0 +1,69 @@
+# Frequently asked questions
+
+Cross-cutting answers with pointers to authoritative pages. For **implementation-heavy** Q&A (stdin in pipelines, `ctx.exitCode`, `bareOsSandboxRunScript`, themes), see [developer-guide/10-glossary-and-faq.md](../developer-guide/10-glossary-and-faq.md).
+
+---
+
+## What is Bare OS, in one sentence?
+
+A **P2P-first** system image stored on **Hyperdrive**: a **seeder** publishes the OS; a **booter** replicates it from **Hyperswarm**, opens **system + personal** drives, and runs **`/boot/init.js`**. See [users-manual/01-what-this-is.md](../users-manual/01-what-this-is.md) and [handbook/01-introduction.md](../handbook/01-introduction.md).
+
+---
+
+## Is this production-ready?
+
+No. Bare OS is **experimental research software**. Expect API, wire, and storage format changes. Read [handbook/00-preface.md](../handbook/00-preface.md) for trust limits and security posture.
+
+---
+
+## How do I run it locally?
+
+Clone the repo, **`npm ci`**, then run **seeder** and **booter** in two terminals (Node or Pear). Step-by-step: [users-manual/03-running-seeder-and-booter.md](../users-manual/03-running-seeder-and-booter.md). Short copy-paste: root [README.md](../README.md).
+
+---
+
+## Why two drives?
+
+The **system** drive is the replicated, Merkle-addressed image (shared semantics). The **personal** drive holds **per-node** state: home, **`/.bare/`**, identity, vault material. The VFS merges them into one tree. [handbook/02-blueprints.md](../handbook/02-blueprints.md), [glossary.md](glossary.md) (“Personal drive”, “System drive”).
+
+---
+
+## What is the MBR? Is it a PC boot sector?
+
+In Bare OS it is a **512-byte** block with magic **`BIOS`** and **Hyperdrive discovery keys**—a bootstrap **for the protocol**, not x86 partition tables. [handbook/03-protocol-and-disk.md](../handbook/03-protocol-and-disk.md), [package-bare-os-protocol.md](reference/package-bare-os-protocol.md).
+
+---
+
+## Where do version numbers live?
+
+[docs/reference/compatibility-matrix.md](reference/compatibility-matrix.md) lists **`bareOsCtxApiVersion`**, **`BARE_OS_KERNEL_FEATURE_BITS_DOC`**, capability wire shape, and lifecycle schema versions with links to source files.
+
+---
+
+## Why doesn’t `import` work in my script on the drive?
+
+In-image scripts are not normal ES modules; the booter evaluates them with **AsyncFunction**. Use **`ctx.bare`**, bundling on the host, or booter-side dependencies. [developer-guide/05-modules-and-imports.md](../developer-guide/05-modules-and-imports.md).
+
+---
+
+## How do I add a `/bin` command?
+
+[developer-guide/06-extending-bin-coreutils.md](../developer-guide/06-extending-bin-coreutils.md) — `src/foo.js`, **`commands.mjs`**, man page JSON, build.
+
+---
+
+## Where is POSIX behavior documented?
+
+[handbook/09-posix-utilities-shell-and-vfs.md](../handbook/09-posix-utilities-shell-and-vfs.md) and [docs/reference/conformance-matrix.md](reference/conformance-matrix.md) (with [posix-conformance-matrix.json](reference/posix-conformance-matrix.json)).
+
+---
+
+## Something failed; where do I start?
+
+[docs/troubleshooting.md](troubleshooting.md) routes symptoms to the user manual, handbook operations chapter, and environment reference.
+
+---
+
+## How do I contribute to documentation?
+
+[docs/CONTRIBUTING-DOCS.md](CONTRIBUTING-DOCS.md) — style, Mermaid, links, terminology rules, and **`npm run pretest`**.