diff --git a/README.md b/README.md
index 1ed32f3..61b514f 100755
--- a/README.md
+++ b/README.md
@@ -25,6 +25,18 @@ liminalOS comes with the Nix package manager (nobody said you need a _unique_ pa
 
 No.
 
+## Hosts
+
+The modules in liminalOS are designed to be utilized by a wide variety of machine configurations, including via nix-darwin on macOS. To that end, modules are organized by operating system (darwin vs. linux), architecture (x86_64 vs. aarch-64), and form factor (desktop vs laptop). Anything that is agnostic of these distinctions is considered a "common module" and allows configuration to be shared between the various host types. This generally includes core programs like CLI tools, the window manager, etc.
+
+The [flake.nix](/flake.nix) currently contains configuration for three hosts:
+
+| Hostname   | Description                                                                                                                                                         |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| "callisto" | a Macbook Pro M1 (2021) running under Asahi Linux. Imports the laptop module sets as well as the core NixOS module sets.                                            |
+| "demeter"  | a custom desktop with an i7-13700KF and RTX 4080. Imports the desktop module, the core NixOS modules, and additionally the gaming module.                           |
+| "phobos"   | Macbook Pro M1 (2021) running macOS with nix-darwin. Imports the core home-manager module as well as some darwin-specific modules for window managers and the like. |
+
 [^1]: also known as GNU/Linux, GNU+Linux, Freedesktop/systemd/musl/busybox Linux, Linux+friends, etc
 
 [^2]: disclaimer: this is unfortunately not actually how the converse works. A => B does not necessarily imply B => A. I hope this satiates the rigor-hungry mathematicians reading.