1 files changed, 41 insertions, 0 deletions
diff --git a/doc/manual.cli b/doc/manual.cli
index eaf8d93..04227f9 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -31,6 +31,47 @@ normally containers but can also be long-running virtual machines. Inside
 virtual machines/containers, \c{bbot} and \c{bslave} run in the \i{worker
 mode} and receive \i{build tasks} from their respective agents.
 
+\h1#arch|Architecture|
+
+Build OS root filesystem (\c{rootfs}) resides entirely in RAM with all changes
+(such as installation of the \c{build2} toolchain} discarded on the next
+reboot. A small amount of persistent (but not precious) state is stored in
+\c{/state} (see \l{#config-storage-state State}).
+
+After booting the kernel, the Build OS execution starts with a custom \c{init}
+script which performs low-level configuration and setup and then hands off the
+initialization to \c{systemd}. At the end of \c{systemd} startup the Build OS
+monitor script (\c{buildos}) is started as a \c{systemd} service. On startup
+this script bootstraps the \c{build2} toolchain, builds the \c{bbot} package,
+and starts it (as another \c{systemd} service) in the agent mode. After that
+the monitor starts monitoring for OS and toolchain changes. If either is
+detected, the host is rebooted, which will trigger both booting the latest
+OS and building of the latest \c{build2} toolchain and \c{bbot}.
+
+@@ TODO: init steps.
+
+The monitor service (and \c{bbot} that it starts) are executed as the
+\c{build} user/group. The home directory of this user is \c{/build}. It has
+the following subdirectories:
+
+\ul|
+
+\li|\n\c{/build/tftp}\n
+
+  A size-limited \c{tmpfs} filesystem that is used to communicate with build
+  machines as well as for build host log access.
+
+  This directory is read-accessible via the TFTP server running on the default
+  port. A \c{bbot} agent also makes sub-directories inside this directory
+  temporarily write-accessible to build machines by running custom instances
+  of the TFTP server on other ports.|
+
+\li|\n\c{/build/machines}\n
+
+  Contains virtual machines and containers. See \l{#config-storage-machines
+  Machines} for details.||
+
+
 \h1#boot|Booting|
 
 \c{buildos} is normally booted from the network using PXE but can also be