From 2e3b262d0558eb0e169c00beac3ba07687684da1 Mon Sep 17 00:00:00 2001
From: Madeleine Sydney <lomiskiam@gmail.com>
Date: Mon, 30 Dec 2024 19:04:41 -0700
Subject: [PATCH] doc: Document users/ and hosts/

---
 README.org | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/README.org b/README.org
index 90ea719..11277fc 100755
--- a/README.org
+++ b/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~