reviewing

docs/playbooks/add-host-toggle.md

@@ -0,0 +1,18 @@
+# Playbook: Add a Host Toggle
+
+- Name: Add or adjust host toggles
+- Purpose: Enable categories, services, or features per host in `hosts/<name>/toggles.nix`.
+- Prerequisites: Identify host role (see Hosts and Roles), secureHost setting, and whether proxies/containers are required.
+- Inputs: Toggle category (apps/dev/scripts/services/servers/units), users list, proxy/container flags, mainServer override, network interface names.
+- Steps:
+  1. Open `hosts/<name>/toggles.nix` and adjust category maps using helper patterns (`enableList` with `mkEnabled`, `mkEnabledWithUsers`, or `mkEnabledIp`).
+  2. Set feature flags such as `enableProxy`, `enableContainers`, and `mainServer` when the host should own proxied services.
+  3. Add service toggles under `servers` with proxy/ip data as needed; align IPs to `my.ips` (e.g., `mkEnabledIp` for remote hosts).
+  4. Ensure `interfaces` entries exist for network-facing services and match `my.interfaces` defaults unless intentionally overridden.
+  5. Reconcile toggle changes with secrets and secureHost: avoid enabling secret-backed services on hosts with `secureHost = false`.
+- Validation:
+  - Toggle sets align with host capabilities and `my.secureHost`.
+  - Proxy- or container-dependent services have `enableProxy`/`enableContainers` enabled.
+  - IP/interface values match `docs/reference/index.md` entries.
+- Outputs: Updated host toggle file reflecting new enablement and infrastructure flags.
+- References: `docs/constitution.md` (Hosts and toggles, Main server and proxies), `docs/reference/index.md` (Hosts and Roles, Proxy rules, Network maps)

docs/playbooks/add-module.md

@@ -0,0 +1,18 @@
+# Playbook: Add a NixOS Module
+
+- Name: Add a module under `modules/<category>/`
+- Purpose: Introduce a new module following auto-import and toggle conventions.
+- Prerequisites: Identify target host(s) and toggle category; confirm `my.secureHost` if secrets are involved.
+- Inputs: Module name, category (apps/dev/scripts/servers/services/shell/network), required options, secret needs, proxy requirements if server-facing.
+- Steps:
+  1. Choose the category path from `docs/reference/index.md` and create `modules/<category>/<name>.nix` (auto-import picks it up; avoid names filtered out such as `librewolf.nix`).
+  2. Define options under `my.<category>` or reuse factories (`mkserver` for servers, `mkscript` for scripts) instead of hand-rolled patterns.
+  3. If the module needs secrets, guard references with `lib.mkIf config.my.secureHost` and map them to the correct secrets file (see secrets map).
+  4. For networked services, align host selection with `my.mainServer` and `my.ips`; enable reverse proxy via `enableProxy` when applicable.
+  5. Wire toggles for target hosts in `hosts/<host>/toggles.nix`, ensuring users/groups and containers/proxy flags are set.
+- Validation:
+  - Module loads without extra imports (auto-import applies).
+  - Toggle wiring matches intended hosts; secureHost gating present for secrets.
+  - Proxy and port choices align with `my.mainServer`, `my.ips`, and firewall rules.
+- Outputs: New module file and updated host toggles if required.
+- References: `docs/constitution.md` (Module Categories, Secrets Map, Main server and proxies), `docs/reference/index.md` (Module Directories, Proxy rules, Secrets Map)

docs/playbooks/add-script.md

@@ -0,0 +1,17 @@
+# Playbook: Add a Script Unit
+
+- Name: Add a script via `mkscript`
+- Purpose: Ship a script package with optional user service and timer.
+- Prerequisites: Identify target users (`my.toggleUsers.scripts` defaults), secureHost status if the script needs secrets, and whether a timer/service is required.
+- Inputs: Script name, package derivation, description, timer schedule, users list, service needs.
+- Steps:
+  1. Add a definition under `my.scripts.<name>` in `modules/scripts/<name>.nix` using `mkscript` options (`enable`, `install`, `service`, `users`, `timer`, `package`, `description`).
+  2. Ensure the package exposes the executable name used by the service/timer.
+  3. For user scoping, set `users` to a single user or list; defaults come from `my.toggleUsers.scripts`.
+  4. If secrets are required, guard references with `lib.mkIf config.my.secureHost` and map them to the appropriate secrets file.
+  5. Enable the script toggle in `hosts/<host>/toggles.nix` under `scripts` or `units`, and ensure timers/services are expected on that host.
+- Validation:
+  - Script installs for intended users; systemd user service/timer activates only when `enable` and `service` are true.
+  - secureHost gating present for any secrets; no orphaned timers.
+- Outputs: New script module and updated host toggles if needed.
+- References: `docs/constitution.md` (Terminology, Secrets Map), `docs/reference/index.md` (Module Directories, Secrets Map, Hosts and Roles)

docs/playbooks/add-secret.md

@@ -0,0 +1,17 @@
+# Playbook: Add a Secret Entry
+
+- Name: Add or update a secret
+- Purpose: Place secrets in the correct SOPS file with secureHost gating.
+- Prerequisites: Target host(s) must have `my.secureHost = true`; identify secret type and consumer service/module.
+- Inputs: Secret name, target file (certs/env/gallery/homepage/keys/wireguard/secrets), owner/group if file material is written, consuming module path.
+- Steps:
+  1. Choose the correct secrets file from the map in `docs/constitution.md` and add the entry there (YAML, encrypted via sops-nix).
+  2. If a private key or file path is required, specify `owner`, `group`, and target path consistent with the consuming module.
+  3. In the consuming module, reference the secret under `config.sops.secrets.<name>` and guard with `lib.mkIf config.my.secureHost`.
+  4. For WireGuard entries, update `secrets/wireguard.yaml` and corresponding interface configuration under the target host.
+  5. Avoid adding secrets for hosts with `secureHost = false`; instead route the workload to a secure host or skip enablement.
+- Validation:
+  - Secret lives in the correct file and encrypts with SOPS; file ownership matches service user where applicable.
+  - Module references are gated by `secureHost` and align with host toggles.
+- Outputs: Updated secrets file and gated module references.
+- References: `docs/constitution.md` (Secrets Map and secureHost), `docs/reference/index.md` (Secrets Map, Hosts and Roles)

docs/playbooks/add-server.md

@@ -0,0 +1,18 @@
+# Playbook: Add a Server Module with mkserver
+
+- Name: Add a reverse-proxied server module
+- Purpose: Stand up a server using `modules/factories/mkserver.nix` with correct proxy and host routing.
+- Prerequisites: Target host must have `my.enableProxy = true` and container support if needed; confirm `my.secureHost` for secrets.
+- Inputs: Service name, desired subdomain, port, proxy type (standard/fix/private), cron needs, secrets/env vars.
+- Steps:
+  1. Create `modules/servers/<name>.nix` and import `mkserver` options to define `enable`, `enableProxy`, `port`, `host`, `hostName`, `url`, `ip`, `enableSocket`, and `certPath` as needed.
+  2. Default host routing uses `my.mainServer` and `my.ips`; override `hostName`/`ip` only when the service must live elsewhere.
+  3. For reverse proxy behavior, select helper from `parts/core.nix`: `proxyReverse` (standard), `proxyReverseFix` (preserve host headers/websockets), or `proxyReversePrivate` (mutual TLS).
+  4. Place secrets/env references in the appropriate file from the secrets map and guard with `lib.mkIf config.my.secureHost`.
+  5. Enable the service toggle in `hosts/<host>/toggles.nix` under `servers` (and `enableProxy` if not already set); add any firewall/static ports needed.
+- Validation:
+  - Service resolves to the expected URL and IP per `my.ips` and `my.mainServer`.
+  - Proxy helper matches the protocol needs; SSL settings align with cert sources.
+  - Secrets load only on secure hosts; firewall assertions pass.
+- Outputs: New server module with mkserver options and updated host toggles/firewall settings.
+- References: `docs/constitution.md` (Main server and proxies, Secrets Map), `docs/reference/index.md` (Proxy rules, Module Directories, Secrets Map, Hosts and Roles)

docs/playbooks/template.md

@@ -0,0 +1,15 @@
+# Playbook Template
+
+- Name:
+- Purpose:
+- Prerequisites: (toggles, hosts, secureHost, required secrets)
+- Inputs: (paths, options, credentials, ports)
+- Steps:
+  1. 
+  2. 
+  3. 
+- Validation:
+  - 
+  - 
+- Outputs:
+- References: `docs/constitution.md` (relevant sections) and `docs/reference/index.md` (paths/hosts/proxies/secrets)