THE HUGE REFACTORING CALENDER WEEK 33; Optimized Matrix and during this updated variables, and implemented better reset and cleanup mode handling, also solved some initial setup bugs

roles/sys-systemctl/README.md

@@ -0,0 +1,52 @@
+# sys-systemctl
+
+Utility role to reset/clean up **systemd** units for a given software stack.  
+It can install a unit-file remover tool, delete units that match a configured suffix, and reload the systemd daemon. The role is designed to run **once per play** and is commonly included by other roles (e.g., timer/service roles) to ensure a clean state before (re)deployment.
+
+## Overview
+
+When `MODE_RESET` is enabled, the role will:
+
+1. Install the configured remover tool/package (via `pkgmgr-install`).
+2. Remove all unit files that match the configured suffix for the current software.
+3. Reload the systemd daemon to apply changes.
+
+A run-once guard (`run_once_sys_systemctl`) prevents repeated execution within the same play run.
+
+## Features
+
+- **Idempotent cleanup** of systemd unit files based on a suffix.
+- **Pluggable remover tool** via `UNIT_SUFFIX_REMOVER_PACKAGE`.
+- **Daemon reload** to immediately apply changes.
+- **Run-once safety** across the play to avoid redundant work.
+
+## Variables
+
+| Variable                     | Type    | Default     | Description                                                                                 |
+|-----------------------------|---------|-------------|---------------------------------------------------------------------------------------------|
+| `MODE_RESET`                | bool    | `false`     | If `true`, executes the reset/cleanup tasks.                                                |
+| `SYS_SERVICE_SUFFIX`        | string  | *required*  | Suffix used to identify unit files belonging to the software stack (e.g., `.infinito.nexus`). |
+| `SOFTWARE_NAME`             | string  | *required*  | Logical software identifier passed to the remover tool.                                      |
+| `UNIT_SUFFIX_REMOVER_PACKAGE` | string| `"unsure"`  | Package/command used to remove the unit files. Must provide a CLI compatible with `-s`.     |
+
+> **Note:** The role expects the remover tool to support a command pattern like:
+> ```
+> <UNIT_SUFFIX_REMOVER_PACKAGE> -s '<SOFTWARE_NAME>'
+> ```
+> Replace `UNIT_SUFFIX_REMOVER_PACKAGE` with your actual utility (or wrapper script) that removes all matching unit files.
+
+## Tasks Flow
+
+- `tasks/main.yml`
+  - Includes `tasks/01_reset.yml` **only when** `MODE_RESET` is `true`.
+  - Loads `utils/run_once.yml` once to set `run_once_sys_systemctl`.
+
+- `tasks/01_reset.yml`
+  - Installs `UNIT_SUFFIX_REMOVER_PACKAGE` via `pkgmgr-install`.
+  - Executes the remover command to purge unit files for `SOFTWARE_NAME` / `SYS_SERVICE_SUFFIX`.
+  - Runs `systemctl daemon-reload`.
+
+## Dependencies
+
+- `pkgmgr-install` (role): used to install `UNIT_SUFFIX_REMOVER_PACKAGE`.
+