diff --git a/launch/README.md b/launch/README.md
index 5464ff5a..c0599bc8 100644
--- a/launch/README.md
+++ b/launch/README.md
@@ -1,7 +1,15 @@
 # service deployment
 
+deploys [NixOS](https://nixos.org/) templates using [OpenTofu](https://opentofu.org/).
+
+## requirements
+
+- [nix](https://nix.dev/)
+
 ## usage
 
+### development
+
 before using other commands, if not using direnv:
 
 ```sh
@@ -13,3 +21,8 @@ then to initialize, or after updating pins or TF providers:
 ```sh
 setup
 ```
+
+## implementing
+
+proper documentation TODO.
+until then, a reference implementation may be found in [`panel/`](https://git.fediversity.eu/Fediversity/Fediversity/src/branch/main/panel).
diff --git a/launch/main.tf b/launch/main.tf
index e89956ea..3c3c4c93 100644
--- a/launch/main.tf
+++ b/launch/main.tf
@@ -91,8 +91,11 @@ resource "terraform_data" "nixos" {
             configuration = {
               # note interpolations here TF ones
               imports = [
-                ${path.root}/options.nix
+                # shared NixOS config
                 ${path.root}/shared.nix
+                # FIXME: separate template options by service
+                ${path.root}/options.nix
+                # for service `mastodon` import `mastodon.nix`
                 ${path.root}/${each.key}.nix
                 # FIXME: get VM details from TF
                 ${path.root}/../infra/test-machines/${each.value.hostname}
@@ -100,7 +103,7 @@ resource "terraform_data" "nixos" {
               # nix path for debugging
               nix.nixPath = [ "${local.nix_path}" ];
             } //
-            # info passed in thru json from TF
+            # template parameters passed in from TF thru json
             builtins.fromJSON "${replace(jsonencode({
               terraform = {
                 domain = var.domain
diff --git a/launch/options.nix b/launch/options.nix
index 4ae70b6e..22344017 100644
--- a/launch/options.nix
+++ b/launch/options.nix
@@ -1,4 +1,4 @@
-# TODO: could (part of) this be generated somehow?
+# TODO: could (part of) this be generated somehow? c.f #275
 {
   lib,
   ...
diff --git a/launch/vars.tf b/launch/variables.tf
similarity index 93%
rename from launch/vars.tf
rename to launch/variables.tf
index 2bc6170b..05f1b2f6 100644
--- a/launch/vars.tf
+++ b/launch/variables.tf
@@ -1,4 +1,4 @@
-# TODO: generate (part of) the variables?
+# TODO: (partially) generate, say from nix modules, c.f. #275
 
 variable "domain" {
   type = string
diff --git a/panel/nix/python-packages/django-pydantic-field/default.nix b/panel/nix/python-packages/django-pydantic-field/default.nix
index 2648a0db..74349e3e 100644
--- a/panel/nix/python-packages/django-pydantic-field/default.nix
+++ b/panel/nix/python-packages/django-pydantic-field/default.nix
@@ -1,3 +1,4 @@
+# TODO upstream, see #248
 {
   lib,
   buildPythonPackage,