OP#427 update Readme

README.md

@@ -6,6 +6,8 @@
 
 - [Readme](#readme)
   - [Synopsis](#synopsis)
+  - [Why This Module Exists](#why-this-module-exists)
+  - [How It Works](#how-it-works)
   - [WARNING](#warning)
   - [Features](#features)
   - [Repo Documentation](#repo-documentation)
@@ -21,9 +23,32 @@
 
 ## Synopsis
 
-Rocky Linux uses yum repos to define its download sources.
+`confdroid_resources` is a lightweight Puppet module that automates the installation and configuration of common YUM/DNF repositories on Rocky Linux (and other Red Hat-based distributions).
+Its primary focus is managing widely used third-party repositories such as EPEL in a clean, idempotent, and conflict-free way.
 
-`confdroid_resources` is a Puppet module to automate installation and configuration of common yum repos like EPEL.
+## Why This Module Exists
+
+Rocky Linux (like other Enterprise Linux distributions) uses **YUM/DNF repositories** to define where packages are downloaded from. Many useful packages — especially development tools, monitoring agents, additional utilities, and more — are not available in the base OS repositories. These packages are commonly found in EPEL (Extra Packages for Enterprise Linux).
+
+However, Puppet follows a **singleton resource model**: a given resource (such as the EPEL repository) can only be declared and managed once in the catalog. Declaring it multiple times causes conflicts and catalog compilation failures.
+
+This creates a common problem:
+
+* Module A needs EPEL to install package X.
+* Module B also needs EPEL to install package Y.
+* If both modules try to declare the EPEL repo resource → conflict.
+
+To solve this, the best practice is to manage foundational repositories (like EPEL) once, in a central place that is included in every node's catalog — regardless of which specific modules or classes are applied.
+That's exactly where `confdroid_resources` comes in.
+
+## How It Works
+
+* The module provides a clean, reusable way to install and enable common repositories (starting with EPEL).
+* It is designed to be included early in the catalog — ideally in a base profile or common role that applies to all nodes.
+* Once the repository is present, any module or class can safely install packages that depend on it without re-declaring the repo resource.
+* Individual repositories can be enabled or disabled via parameters, giving you full control without touching the main resource declarations.
+
+This approach keeps your catalog clean, avoids duplication, and prevents resource conflicts.
 
 ## WARNING
 
@@ -32,8 +57,11 @@ Rocky Linux uses yum repos to define its download sources.
 ## Features
 
 * installs and configures yum repos
-* allows enabling or disabling EPEL even if the repo is installed, via `$rs_enable_epel`.
+* Automatic installation and enabling of EPEL via `$rs_enable_epel`. since this parameter is directly also used in the yumrepo configuration, it needs to be set to `1`, **not** `true`.
+* Parameter-based control (enable/disable specific repos)
+* Idempotent and conflict-free design
 
+More repositories (PowerTools/CRB, RPM Fusion, etc.) will be added over time.
 
 ## Repo Documentation
 
@@ -55,12 +83,16 @@ node 'example.example.net' {
 }
 ```
 
-* through Foreman:
+* through Foreman (recommended):
 
 In order to apply parameters through Foreman, the params.pp must be added to the host or host group in question.
 
 See [more details about class deployment on Confdroid.com](https://confdroid.com/2017/05/deploying-our-puppet-modules/).
 
+* call it from other modules
+```bash
+require confdroid_resources
+```
 ## SELINUX
 
 All files and directories are configured with correct selinux context. If selinux is disabled, these contexts are ignored.
@@ -70,7 +102,7 @@ All files and directories are configured with correct selinux context. If selinu
 ## Support
 
 * OS: Rocky 9
-* Puppet 6,8
+* Puppet 8
 
 ## Tests
 
@@ -84,6 +116,7 @@ All files and directories are configured with correct selinux context. If selinu
 ## Contact Us
 
 [contact Us](https://confdroid.com/contact/)
+[Feedback Portal](feedback.confdroid.com)
 
 ## Disclaimer