chore: stub option schema + lib + lnbits service wrapper

core.nix defines the lnbits-sensei.* options (user, host, features,
backend). lib.nix reserves the config.lnbits-sensei.lib helper namespace
with placeholder stubs. lnbits.nix is a no-op stub that documents the
intended services.lnbits wrap shape and the FakeWallet default.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

modules/core.nix

@@ -0,0 +1,103 @@
+# lnbits-sensei — option schema.
+#
+# All host configuration is expressed through `config.lnbits-sensei.*`
+# options defined here. Modules consume these via `lib.mkIf` / option
+# reads; they never read raw `settings` outside the configuration.nix
+# wire-up. This indirection lets multiple hosts share modules and lets
+# the dev-env / lnbits modules toggle behaviour on feature flags
+# without coupling to file layout.
+{
+  config,
+  lib,
+  ...
+}:
+
+let
+  inherit (lib) mkEnableOption mkOption types;
+in
+{
+  options.lnbits-sensei = {
+    enable = mkEnableOption "lnbits-sensei NixOS scaffold";
+
+    # --- Identity ---
+
+    user = mkOption {
+      type = types.str;
+      default = "user";
+      description = "Primary user on this host. Sourced from settings.nix.";
+      example = "alice";
+    };
+
+    hostName = mkOption {
+      type = types.str;
+      default = "lnbits-sensei";
+      description = "NixOS hostname. Sourced from settings.nix.";
+    };
+
+    # --- Feature flags ---
+    #
+    # Mirror the omnixy pattern: simple on/off switches gating both
+    # system packages and home-manager packages. Default off so a
+    # fresh checkout builds a minimal host until the consumer opts in.
+
+    features = {
+      coding = mkEnableOption ''
+        Development tooling for working on LNbits itself (python, poetry,
+        nodejs, pre-commit). Off by default — flip on if this host is
+        your LNbits dev box rather than a runner
+      '';
+
+      regtest = mkEnableOption ''
+        Full Bitcoin/Lightning regtest docker stack (LND + CLN + Eclair
+        + bitcoind + electrs). Implies a container engine. See
+        modules/dev-env/regtest.nix and modules/dev-env/scripts/regtest.sh
+      '';
+
+      fakewallet = mkEnableOption ''
+        FakeWallet dev mode — no docker, no chains, nothing to start.
+        Default LNbits backend; this flag mostly controls dev-env
+        helpers and symmetry with the regtest workflow
+      '';
+    };
+
+    # --- LNbits service config ---
+
+    lnbits = {
+      backend = mkOption {
+        type = types.enum [
+          "FakeWallet"
+          "LndRestWallet"
+          "CoreLightningWallet"
+          "EclairWallet"
+        ];
+        default = "FakeWallet";
+        description = ''
+          Which Lightning backend LNbits talks to. FakeWallet is the
+          default — no real chain, no docker, nothing to start. The
+          regtest dev mode (modules/dev-env/regtest.nix) flips this to
+          LndRestWallet or CoreLightningWallet at activation time.
+        '';
+        example = "LndRestWallet";
+      };
+
+      port = mkOption {
+        type = types.port;
+        default = 5000;
+        description = "TCP port LNbits binds to.";
+      };
+
+      host = mkOption {
+        type = types.str;
+        default = "127.0.0.1";
+        description = ''
+          Bind address. Defaults to loopback; put a reverse proxy in
+          front for any host reachable from outside localhost.
+        '';
+      };
+    };
+  };
+
+  # No config body here — configuration.nix and the per-feature modules
+  # consume these options. This file is options-only on purpose so the
+  # schema is greppable in one place.
+}

modules/lib.nix

@@ -0,0 +1,58 @@
+# lnbits-sensei — shared helper functions.
+#
+# Exposed via `config.lnbits-sensei.lib` so every module can access
+# helpers without `import ./lib.nix` cycles. Mirrors omnixy's
+# modules/lib.nix pattern — this is the only place helpers are defined.
+#
+# Skeleton-only: placeholders showing the intended shape. Real
+# implementations land alongside the first module that needs them.
+{
+  config,
+  pkgs,
+  lib,
+  ...
+}:
+
+let
+  inherit (lib) mkOption types;
+  cfg = config.lnbits-sensei;
+
+  helpers = {
+    # Feature flag predicate.
+    # isEnabled = feature: cfg.features.${feature} or false;
+    isEnabled = _feature: false;
+
+    # Resolve a path under the primary user's home dir.
+    # userPath = path: "/home/${cfg.user}/${path}";
+    userPath = _path: throw "lnbits-sensei.lib.userPath: not yet implemented";
+
+    # Wrap a body in `mkIf (isEnabled feature)`.
+    # withFeature = feature: body: lib.mkIf (helpers.isEnabled feature) body;
+    withFeature = _feature: _body: throw "lnbits-sensei.lib.withFeature: not yet implemented";
+
+    # `pkgs.writeShellScriptBin` with our house preamble (set -euo
+    # pipefail, shebang via /usr/bin/env bash for NixOS).
+    # makeScript = name: description: body: pkgs.writeShellScriptBin name ''…'';
+    makeScript =
+      _name: _description: _body: throw "lnbits-sensei.lib.makeScript: not yet implemented";
+
+    # Standard on-disk locations the modules agree on.
+    paths = {
+      # config = "/etc/nixos";
+      # state  = "/var/lib/lnbits-sensei";
+      # logs   = "/var/log/lnbits-sensei";
+    };
+  };
+
+in
+{
+  options.lnbits-sensei.lib = mkOption {
+    type = types.attrs;
+    internal = true;
+    description = "lnbits-sensei shared helpers (internal — see modules/lib.nix).";
+  };
+
+  config = {
+    lnbits-sensei.lib = helpers;
+  };
+}

modules/lnbits.nix

@@ -0,0 +1,42 @@
+# lnbits-sensei — LNbits service wrapper.
+#
+# Stub. Wraps an as-yet-unwritten `services.lnbits` NixOS module (or
+# a hand-rolled systemd unit) and exposes the small surface area
+# consumers actually tune: backend, port, host. Sourced from
+# `config.lnbits-sensei.lnbits.*` so the option schema stays in
+# modules/core.nix.
+#
+# Default `backend = "FakeWallet"` — no docker, no chains, nothing to
+# start. The regtest mode (modules/dev-env/regtest.nix, scripts/regtest.sh)
+# flips this to LndRestWallet / CoreLightningWallet and wires the
+# credentials from the regtest stack's generated artifacts.
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+
+let
+  inherit (lib) mkIf;
+  cfg = config.lnbits-sensei;
+in
+{
+  config = mkIf cfg.enable {
+    # TODO(skeleton): wire services.lnbits (or a hand-rolled systemd
+    # user/system unit) here. Intended shape:
+    #
+    #   services.lnbits = {
+    #     enable = true;
+    #     backend = cfg.lnbits.backend;
+    #     host    = cfg.lnbits.host;
+    #     port    = cfg.lnbits.port;
+    #     # source = inputs.lnbits-src; (resolved in flake.nix → specialArgs)
+    #   };
+    #
+    # Until a real services.lnbits module is published in nixpkgs,
+    # the substantive pass will likely declare a systemd.services.lnbits
+    # entry that runs `poetry run lnbits` out of a checkout of
+    # `inputs.lnbits-src`.
+  };
+}