docs: update CLAUDE.md and AGENTS.md for entity-based architecture

- Update architecture section to reflect actual file structure
- Document entity system (sensor, binary_sensor, switch, light, button)
- Add MQTT topic documentation
- Add NixOS/home-manager integration section
- Update commands section
- Replace metrics-specialist with entity-specialist
- Replace events-specialist with nix-specialist
- Update mqtt-specialist context for current topic structure

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

AGENTS.md

@@ -27,17 +27,17 @@ Use this agent to review code changes before committing.
 
 **Trigger:** Before creating commits or PRs.
 
-## metrics-specialist
+## entity-specialist
 
-Use this agent when working on system metric collection.
+Use this agent when working on entity configuration or the entity system.
 
 **Responsibilities:**
-- Understand Linux /proc and /sys interfaces
+- Understand entity types (sensor, binary_sensor, switch, light, button)
-- Know cross-platform metric collection strategies
+- Design shell commands for state polling and actions
-- Ensure metrics are properly typed and documented
+- Ensure proper Home Assistant discovery payloads
-- Validate metric units and normalization
+- Validate entity configuration options
 
-**Context:** Systant collects CPU, memory, disk, and network metrics. Metrics should be normalized (percentages 0-100, bytes for sizes) and include metadata for Home Assistant discovery.
+**Context:** Systant uses a unified "entity" system where all metrics and controls are defined as entities in TOML config. Each entity has a `state_command` and optionally `on_command`/`off_command`/`press_command` depending on type.
 
 ## mqtt-specialist
 
@@ -50,20 +50,19 @@ Use this agent when working on MQTT publishing or Home Assistant integration.
 - Handle connection lifecycle (connect, reconnect, disconnect)
 - Design topic hierarchies for commands and events
 
-**Context:** Systant publishes to MQTT with Home Assistant auto-discovery. Topics follow the pattern `systant/{hostname}/{metric_type}`. Command topics use `systant/{hostname}/command/{action}`.
+**Context:** Systant publishes to MQTT with Home Assistant auto-discovery. Topics follow the pattern `systant/{hostname}/{entity_id}/state` for state updates, `systant/{hostname}/{entity_id}/set` for switch/light commands, and `homeassistant/{type}/{hostname}_{entity_id}/config` for discovery.
 
-## events-specialist
+## nix-specialist
 
-Use this agent when working on the event/command system.
+Use this agent when working on Nix packaging or the home-manager module.
 
 **Responsibilities:**
-- Design secure command execution with allowlists
+- Maintain the Nix flake and package definition
-- Implement event handlers and action dispatching
+- Update the home-manager module options
-- Ensure proper input validation and sanitization
+- Handle fixed-output derivations for npm dependencies
-- Handle timeouts and error reporting
+- Ensure cross-system compatibility
-- Consider security implications of remote command execution
 
-**Context:** Systant listens for MQTT commands and executes configured actions. Security is paramount - all commands must be validated against an allowlist, inputs sanitized, and execution sandboxed where possible.
+**Context:** Systant is packaged as a Nix flake with a home-manager module. The package uses a two-phase build: FOD for `bun install`, then `bun build --compile` for the binary. The home-manager module creates a systemd user service.
 
 ## debug-investigator
 

CLAUDE.md

@@ -16,30 +16,49 @@ Systant is a lightweight CLI tool written in Bun/TypeScript that:
 ### Architecture
 
 ```
-index.ts              # CLI entry point (yargs)
+index.ts              # CLI entry point
 src/
-  commands/           # CLI command handlers
+  config.ts           # TOML configuration loading
-  metrics/            # System metric collectors
+  mqtt.ts             # MQTT client, publishing, and HA discovery
-  mqtt/               # MQTT client and publishing
+  entities.ts         # Entity management (state polling, command handling)
-  events/             # MQTT event listeners and handlers
-  actions/            # Executable actions (shell, service, notify)
-  ha/                 # Home Assistant discovery
-  config/             # Configuration loading
 ```
 
-### Event/Command System
+### Entity System
 
-Systant subscribes to MQTT topics and executes configured actions:
+Systant uses a unified "entity" concept that combines state monitoring and command handling. Entity types:
 
-```
+- **sensor**: Read-only numeric/string values (CPU usage, temperature, etc.)
-Topic: systant/{hostname}/command/{action}
+- **binary_sensor**: Read-only on/off states (service running, etc.)
-Payload: { "args": [...], "timeout": 30 }
+- **switch**: Controllable on/off with `on_command` and `off_command`
+- **light**: Same as switch, for display/monitor control
+- **button**: Press-only actions with `press_command`
 
-Topic: systant/{hostname}/event/{event_name}
+Each entity is defined in TOML with shell commands:
-Payload: { ... event data ... }
+
+```toml
+[entities.cpu_usage]
+type = "sensor"
+state_command = "awk '/^cpu / {print int(($2+$4)*100/($2+$4+$5))}' /proc/stat"
+unit = "%"
+icon = "mdi:chip"
+name = "CPU Usage"
+
+[entities.headphones]
+type = "switch"
+state_command = "pactl get-default-sink | grep -q usb && echo ON || echo OFF"
+on_command = "pactl set-default-sink alsa_output.usb-..."
+off_command = "pactl set-default-sink alsa_output.pci-..."
 ```
 
-Actions are sandboxed and configurable via allowlists in the config file. Security is critical - never execute arbitrary commands without validation.
+### MQTT Topics
+
+```
+systant/{hostname}/{entity_id}/state      # State updates
+systant/{hostname}/{entity_id}/set        # Commands (for switch/light)
+systant/{hostname}/{entity_id}/press      # Button presses
+systant/{hostname}/availability           # Online/offline status
+homeassistant/{type}/{hostname}_{id}/config  # HA auto-discovery
+```
 
 ### Key Design Decisions
 
@@ -51,10 +70,29 @@ Actions are sandboxed and configurable via allowlists in the config file. Securi
 ## Tech Stack
 
 - **Runtime**: Bun (not Node.js)
-- **CLI**: yargs
+- **Config**: TOML (smol-toml)
-- **Config**: TOML
+- **MQTT**: mqtt.js
-- **MQTT**: mqtt.js or Bun-native when available
+- **Packaging**: Nix flake with home-manager module
-- **Package**: Nix flake for reproducible builds
+
+### NixOS/Home Manager Integration
+
+```nix
+# flake.nix inputs
+inputs.systant.url = "git+ssh://...";
+
+# Add overlay for pkgs.systant
+nixpkgs.overlays = [ inputs.systant.overlays.default ];
+
+# Import home-manager module
+home-manager.sharedModules = [ inputs.systant.homeManagerModules.default ];
+
+# In user config
+services.systant = {
+  enable = true;
+  settings = { /* TOML as Nix attrset */ };
+  # or: configFile = ./systant.toml;
+};
+```
 
 ## Bun Conventions
 
@@ -105,10 +143,17 @@ Watch mode: `bun test --watch`
 ## Commands
 
 ```bash
-bun run start        # Run in development
+# Development
-bun run dist         # Build standalone binary
+bun run index.ts run --config systant.toml
-bun test             # Run tests
+
-bun test --watch     # Watch mode
+# Build standalone binary
+bun build index.ts --compile --outfile systant
+
+# Nix build
+nix build .#systant
+
+# Run tests
+bun test
 ```
 
 ## Planning Protocol

flake.nix

@@ -12,8 +12,8 @@
       ...
     }:
     {
-      # NixOS module (system-independent)
+      # Home Manager module (system-independent)
-      nixosModules.default = import ./nix/nixos-module.nix;
+      homeManagerModules.default = import ./nix/nixos-module.nix;
 
       # Overlay to add systant to pkgs
       overlays.default = final: prev: {

nix/nixos-module.nix

@@ -1,11 +1,17 @@
 { config, lib, pkgs, ... }:
 
 let
-  cfg = config.systant;
+  cfg = config.services.systant;
   settingsFormat = pkgs.formats.toml { };
+  configFile =
+    if cfg.configFile != null
+    then cfg.configFile
+    else if cfg.settings != { }
+    then settingsFormat.generate "systant-config.toml" cfg.settings
+    else null;
 in
 {
-  options.systant = {
+  options.services.systant = {
     enable = lib.mkEnableOption "systant system monitoring agent";
 
     package = lib.mkOption {
@@ -53,70 +59,30 @@ in
         }
       '';
     };
-
-    user = lib.mkOption {
-      type = lib.types.str;
-      default = "systant";
-      description = "User account under which systant runs.";
-    };
-
-    group = lib.mkOption {
-      type = lib.types.str;
-      default = "systant";
-      description = "Group under which systant runs.";
-    };
   };
 
   config = lib.mkIf cfg.enable {
-    # Create systant user/group if using defaults
+    home.packages = [ cfg.package ];
-    users.users.${cfg.user} = lib.mkIf (cfg.user == "systant") {
+
-      isSystemUser = true;
+    systemd.user.services.systant = {
-      group = cfg.group;
+      Unit = {
-      description = "Systant service user";
+        Description = "Systant system monitoring agent";
+        After = [ "network-online.target" ];
+        Wants = [ "network-online.target" ];
       };
 
-    users.groups.${cfg.group} = lib.mkIf (cfg.group == "systant") { };
+      Service = {
-
-    # Generate config file from settings if configFile not provided
-    environment.etc."systant/config.toml" = lib.mkIf (cfg.configFile == null && cfg.settings != { }) {
-      source = settingsFormat.generate "systant-config.toml" cfg.settings;
-    };
-
-    systemd.services.systant = {
-      description = "Systant system monitoring agent";
-      wantedBy = [ "multi-user.target" ];
-      after = [ "network-online.target" ];
-      wants = [ "network-online.target" ];
-
-      serviceConfig = {
         Type = "simple";
-        User = cfg.user;
-        Group = cfg.group;
         ExecStart =
-          let
+          if configFile != null
-            configPath =
+          then "${cfg.package}/bin/systant run --config ${configFile}"
-              if cfg.configFile != null
+          else "${cfg.package}/bin/systant run";
-              then cfg.configFile
-              else "/etc/systant/config.toml";
-          in
-          "${cfg.package}/bin/systant run --config ${configPath}";
         Restart = "on-failure";
         RestartSec = "5s";
+      };
 
-        # Hardening
+      Install = {
-        NoNewPrivileges = true;
+        WantedBy = [ "default.target" ];
-        ProtectSystem = "strict";
-        ProtectHome = true;
-        PrivateTmp = true;
-        ProtectKernelTunables = true;
-        ProtectKernelModules = true;
-        ProtectControlGroups = true;
-
-        # Allow reading system metrics
-        ReadOnlyPaths = [
-          "/proc"
-          "/sys"
-        ];
       };
     };
   };