docs: rewrite README

README.md

@@ -1,28 +1,40 @@
 # *Aἰθήρ*
 
-> [*Aither*] as a whole neither came into being nor admits of destruction,
+> [*Aither*] as a whole neither came into being nor admits of destruction, but
-> but is one and eternal, with no end or beginning of its total
+> is one and eternal, with no end or beginning of its total duration, containing
-> duration, containing and embracing in itself the infinity of time ...
+> and embracing in itself the infinity of time ...
 >
 > — Aristotle, *On the Heavens* [^1]
 
 Aether is a fully automated web server configured via **pure** and
-**declarative** package management, powered by [NixOS](https://nixos.org).
+**declarative** package management, powered by [NixOS](https://nixos.org). This
-This allows for all aspects of the server's operation, including config files,
+allows for all aspects of the server's operation, including config files,
 software dependencies, and site content to be deployed and provisioned
 automatically.
 
-In short, it's my personal web server.
+In short, it's my personal web server. It's also a NixOS codebase to support
+that server, designed for generic use in other configurations.
 
 ## Modules
 
-As with all good NixOS configurations, Aether is split into *modules* that
+As with all good NixOS configurations, Aether is split into *modules*. Each is
-each provide different functionality. These are stored in the `modules/` directory.
+stored as a subdirectory of the `modules/` directory and defines an specific
+function of the server.
+
+Modules are publicly exposed by this flake as `nixosModules.<name>`, and can be
+imported to activate their functionality. Any number of modules can be imported
+independently, and the special `nixosModules.all` flake output can be used to
+import every module at once.
+
+Some modules have options that can be used to configure their effects. If a
+module has options, they can be found in the `options.nix` file inside the
+module directory. More general options used by multiple modules are documented
+in `modules/options.nix`.
 
 ### Module Checklist
 
 - [x] `basic` - Basic Internet support
-- [x] `ssh` - SSH configuration
+- [x] `ssh` - SSH support
 - [ ] `site` - Static site hosting
 - [x] `fail2ban` - IP moderation
 - [x] `forgejo` - Code forge
@@ -33,19 +45,29 @@ each provide different functionality. These are stored in the `modules/` directo
 ## Deployment
 
 Aether is designed to separate individual machine details from the abstract
-specification of the system, allowing for its code to be used for many
+specification of the system, allowing for its code to be used for many different
-different types of system. This is handled using *deployments* in the
+types of system. This is handled using *deployments* in the `deploy/` directory.
-`deploy/` directory.
+
+Each deployment module is exposed as `nixosModules.deploy-<name>`. Only one
+deployment should be imported; if Aether detects that more than one is imported,
+it will prevent the configuration from building.
 
 Currently, I deploy Aether physically to a
 [Raspberry Pi 5](https://wiki.nixos.org/wiki/NixOS_on_ARM/Raspberry_Pi_5)
 running a [modified UEFI bootloader](https://github.com/worproject/rpi5-uefi)
-to provide Linux support. The NixOS code for this can be found in `deploy/rpi5/`.
+to provide Linux support. The NixOS code for this can be found in
+`deploy/rpi5/`, and it is exposed as `nixosModules.deploy-rpi5`.
+
+> [!IMPORTANT] A complete rewrite of the deployment system using
+> [NixOps 4](https://github.com/nixops4/nixops4) is planned once that project is
+> stabilized. This may result in breaking changes to Aether's public interface.
 
 ## External Usage
 
-If you use NixOS and are interested in any of these modules, you can import
+If you use NixOS and are interested in any of these modules, you can import them
-them for your own config!
+for your own config!
+
+### Flake-Based Configuration
 
 Add this repository as a flake input:
 
@@ -55,13 +77,25 @@ Add this repository as a flake input:
 }
 ```
 
-Aether modules are then exposed under `nixosModules.<name>` and deployments
+Aether's modules can then be accessed as flake outputs. In particular, the
-under `nixosModules.deploy-<name>`. You can activate a module by adding it
+`specialArgs` parameter can be used to expose the modules in your configuration:
-to your `imports`:
 
 ``` nix
+nixpkgs.lib.nixosSystem {
+  specialArgs = {
+    aether = aether.nixosModules;
+  };
+  modules = [
+    ./config.nix
+  ];
+}
+```
+
+``` nix
+# -- config.nix --
+{ aether, ... }:
 {
-  imports = with aether.nixosModules; [
+  imports = with aether; [
     # Deployment
     deploy-rpi5
     # Modules
@@ -69,19 +103,13 @@ to your `imports`:
     ssh
   ];
 
-  # Required by forgejo module
+  # Required module option
   aether.domain = "...";
 }
 ```
 
-Any number of modules can be activated at once, and the special
+For a more complete example of how to use Aether modules, my personal server
-`nixosModules.aether` output can be used to refer to every module at once.
+config can be found in the `aether/` directory.
-Activating more than one deployment will cause issues, so that should be
-avoided.
 
-Some modules have options that can be used to configure their effects. If a
+[^1]: Adapted from
-module has options, they can be found in the `options.nix` file inside the
+      [Book II.1](http://classics.mit.edu/Aristotle/heavens.2.ii.html).
-module directory. More general options used by multiple modules are
-documented in `modules/options.nix`.
-
-[^1]: Adapted from [Book II.1](http://classics.mit.edu/Aristotle/heavens.2.ii.html).