docs: document Nix flake and home-manager module usage

README.md

@@ -6,7 +6,7 @@ Connects to Fastmail's JMAP EventSource stream and delivers new messages directl
 
 ## How it works
 
-On first run — or when the saved JMAP state is too stale — mbrts falls back to `mbsync` for a full sync, then takes over from that point.
+On first run, or when the saved JMAP state is stale, mbrts falls back to `mbsync` for a full sync, then takes over from that point.
 
 ## Setup
 
@@ -45,6 +45,60 @@ mbrts --name Personal \
 
 Run `mbrts --help` for the full flag list, or `mbrts --version` to print the version.
 
+### Nix
+
+Add mbrts as a flake input:
+
+```nix
+inputs.mbrts = {
+  url = "git+https://code.adriano.fyi/me/mbrts";
+  inputs.nixpkgs.follows = "nixpkgs";
+};
+```
+
+The flake exposes:
+
+| Output | Description |
+|---|---|
+| `packages.*.default` | The `mbrts` binary |
+| `overlays.default` | Adds `pkgs.mbrts` |
+| `homeManagerModules.default` | The `services.mbrts` home-manager module |
+
+### home-manager module
+
+Add the overlay and module to your home-manager configuration, then configure the service:
+
+```nix
+# in your flake outputs
+overlays = [ inputs.mbrts.overlays.default ];
+
+# in your home-manager module list
+inputs.mbrts.homeManagerModules.default
+
+# in your home-manager config
+services.mbrts = {
+  enable = true;
+  accounts = [
+    {
+      name = "Personal";
+      maildirPath = "/home/you/.mail/Personal";
+      passwordCommand = "pass show fastmail/api-token";
+    }
+  ];
+};
+```
+
+The module generates a config file and runs mbrts as a `systemd` user service. Logs are available via `journalctl --user -u mbrts -f`.
+
+Module options:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `enable` | bool | — | Enable the service |
+| `package` | package | `pkgs.mbrts` | Package to use |
+| `logLevel` | enum | `"info"` | `debug`, `info`, `warn`, or `error` |
+| `accounts` | list | `[]` | List of account submodules (see config file fields above) |
+
 ## Build
 
 ```