doc: Document users/ and hosts/

README.org

@@ -28,6 +28,51 @@ In order of descending preference, user programs should be configured by...
 
 * Conventions
 
+** Repo structure
+
+*** =hosts/=
+
+Each directory =hosts/«HOST»= is expected to configure a single specific device, where =«HOST»= is the device's exact hostname. Said directory =«HOST»= should have at least the following structure:
+
+#+begin_example
+hosts
+└── «HOST»
+    ├── configuration.nix
+    └── system.nix
+#+end_example
+
+Where =configuration.nix= is the main entry point imported by the top-level flake, and =system.nix= evaluates to a string corresponding to the =system= option to be used.
+
+*** =users/=
+
+Similarly to the =hosts= directory, each subdirectory =users/«USER»= is assumed to have some structure, and that =«USER»= is the precise username desired.
+
+#+begin_example
+users
+└── «USER»
+    └── default.nix
+#+end_example
+
+Where =default.nix= returns an attrset of form
+
+#+begin_src nix
+{
+  # The NixOS option `users.users.«USER»` will be set to result of
+  # `systemConfiguration`.
+  systemConfiguration = { config, pkgs, lib, ... }: {
+    # isNormalUser = true;
+    # extraGroups = [ "wheel" ];
+    # ...
+  };
+
+  # Home-manager configuration
+  homeConfiguration = { config, pkgs, lib, ... }: {
+    # home.packages = [ pkgs.hello ];
+    # ...
+  };
+}
+#+end_src
+
 ** Impermanence and persistence
 
 - Persistent files to be linked into ~/~ go under ~/persist/root~