Update README to enhance clarity on module features and usage

Author: marko-stanojevic

README.md

@@ -1,24 +1,40 @@
 # PSScriptModule - PowerShell Script Module Template
 
-A production-ready PowerShell script module template designed to streamline the creation, testing, and delivery of enterprise-grade PowerShell modules. This template implements modern DevOps practices,
-automated quality gates, and continuous delivery workflows right out of the box.
+> A modern PowerShell module template with CI/CD, testing, semantic versioning, and automated publishing
+
+A production-ready PowerShell module template with built-in CI/CD, testing, versioning, and publishing workflows using GitHub Actions.
 
 [![CI](https://github.com/WarehouseFinds/PSScriptModule/actions/workflows/ci.yml/badge.svg)](https://github.com/WarehouseFinds/PSScriptModule/actions/workflows/ci.yml)
 [![Code Coverage](https://img.shields.io/github/actions/workflow/status/WarehouseFinds/PSScriptModule/ci.yml?branch=main&label=code%20coverage)](https://github.com/WarehouseFinds/PSScriptModule/actions/workflows/ci.yml)
 [![PowerShell Gallery](https://img.shields.io/powershellgallery/v/PSScriptModule.svg)](https://www.powershellgallery.com/packages/PSScriptModule)
 [![Downloads](https://img.shields.io/powershellgallery/dt/PSScriptModule.svg)](https://www.powershellgallery.com/packages/PSScriptModule)
 [![License](https://img.shields.io/github/license/WarehouseFinds/PSScriptModule)](LICENSE)
 
-## 🎯 Purpose
+## 💡 Why This Template?
+
+Most PowerShell module repositories start the same way: a few scripts, some manual testing, and CI/CD added later—often inconsistently. This template flips that model.
+
+**PSScriptModule is opinionated by design.**  
+It gives you a complete, production-grade foundation so you can focus on writing PowerShell code—not wiring pipelines.
+
+### What makes it different?
+
+- **CI/CD from day one**  
+  Build, test, analyze, version, and publish automatically using GitHub Actions.
+
+- **Best practices baked in**  
+  Module structure, testing, security scanning, and documentation follow proven PowerShell and DevOps conventions.
+
+- **Automation over ceremony**  
+  Versioning, changelogs, releases, and publishing happen automatically based on your commits and pull requests.
 
-This template solves the common challenge of setting up a professional PowerShell module project from scratch. Instead of manually configuring build scripts, testing frameworks, and CI/CD pipelines,
-you can clone this repository and start writing your module's business logic immediately.
+- **Works everywhere**  
+  Tested on Windows, Linux, and macOS, with optional devcontainer support for consistent environments.
 
-**Perfect for:**
+- **Scales with your project**  
+  Suitable for prototypes, internal tooling, and fully open-source modules published to the PowerShell Gallery.
 
-- Open-source PowerShell projects
-- Rapid prototyping of PowerShell modules
-- Learning PowerShell module development best practices
+If you’ve ever thought *“I just want to write PowerShell, not build pipelines”*, this template is for you.
 
 ## 🎬 How to Use This Template
 
@@ -31,40 +47,39 @@ you can clone this repository and start writing your module's business logic imm
 
 ## 📦 Features
 
-When you create a module from this template, you immediately get:
+When you create a module from this template, you get a fully wired, production-ready PowerShell module from day one.
 
-✅ **CI/CD Ready**
+### ✅ CI/CD Ready
 
-- GitHub Actions workflows for CI, release, publishing and more
-- Dependency management and caching
-- Compatibility testing on Windows, Linux, and macOS
+- End-to-end GitHub Actions workflows for build, test, release, and publishing
+- Dependency management with intelligent caching for faster pipelines
+- Cross-platform validation on Windows, Linux, and macOS
 - Automated publishing to PowerShell Gallery and NuGet.org
 
-✅ **Development Environment**
+### ✅ Development Environment
 
-- VS Code configuration (settings, recommended extensions)
-- Build tasks pre-configured
-- Run and debug configurations
-- Devcontainer support for preconfigured sandboxed environments
+- Opinionated VS Code setup (settings and recommended extensions)
+- Pre-configured build, run, and debug tasks
+- Devcontainer support for consistent, sandboxed development environments
 
-✅ **Version Management**
+### ✅ Version Management
 
-- GitVersion for semantic versioning
-- GitHub Flow (v1) release workflow
-- Commit-based version bumps with `+semver:` keywords
-- Changelog generation based on merged PRs
+- Semantic versioning powered by GitVersion
+- GitHub Flow–based release strategy
+- Commit-driven version bumps using `+semver:` keywords
+- Automatic changelog generation from merged pull requests
 
-✅ **Code Quality and Testing**
+### ✅ Code Quality and Testing
 
-- Pester test framework for unit tests
+- Pester-based unit testing framework
 - Code coverage reporting
-- Security scanning (PSScriptAnalyzer + InjectionHunter + CodeQL)
+- Built-in security scanning with PSScriptAnalyzer, InjectionHunter, and CodeQL
 
-✅ **Project Documentation**
+### ✅ Project Documentation
 
-- Markdown-based help generation with PlatyPS
-- Auto-generated external help files for `Get-Help`
-- Comprehensive documentation guides in `/docs`
+- Markdown-based help generation using PlatyPS
+- Auto-generated external help for `Get-Help`
+- Structured, comprehensive documentation in the `/docs` directory
 
 ## 📂 Project Structure
 
@@ -77,7 +92,7 @@ PSScriptModule/
 ├── 📄 AGENTS.md                     // AI agent instructions
 ├── 📁 src/                          // Source code
 │   ├── 📄 PSScriptModule.psd1       // Module manifest
-|   ├── 📁 Classes/                  // Classes definitions
+│   ├── 📁 Classes/                  // Classes definitions
 │   ├── 📁 Public/                   // Public functions (exported)
 │   └── 📁 Private/                  // Private functions (internal only)
 ├── 📁 tests/                        // Test suites
@@ -130,7 +145,7 @@ Personalize it by updating the name, description, and visibility.
    Invoke-PSDepend -Path ./requirements.psd1 -Install -Import -Force
    ```
 
-1. Run Build and test tasks:
+1. Run build and test tasks:
 
    ```powershell
    # Run default build (Clean + Build)
@@ -150,7 +165,7 @@ After setup, customize your module:
    - Set `Author`, `CompanyName`, `Copyright`
    - Update `Description` and `Tags`
 
-   > **Note**: Do not change `ModuleVersion`, `RootModule` and `FunctionsToExport`  - it is managed automatically
+   > **Note**: Do not change `ModuleVersion`, `RootModule`, or `FunctionsToExport`  - it is managed automatically
 
 1. **Start Developing**:
    - Add functions to `src/Public/` (exported) or `src/Private/` (internal)