docs: enhance README with clearer structure and usage examples (#26)

Author: FidelusAleksander

README.md

@@ -1,38 +1,24 @@
-# Action: Text Variables
+# Text Variables Action 📝
 
-Replace mustache style variables in text templates. Returns modified text as an
-output for use in other actions.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub release](https://img.shields.io/github/release/skills/action-text-variables.svg)](https://github.com/skills/action-text-variables/releases)
+[![Continuous Integration](https://github.com/skills/action-text-variables/actions/workflows/ci.yml/badge.svg)](https://github.com/skills/action-text-variables/actions/workflows/ci.yml)
 
-Typical uses:
+Replace mustache style variables (`{{ variable }}`) in text templates. Returns
+modified text as an output for use in other actions.
 
-- Dynamically build an Issue or Pull Request description, beyond GitHub's
-  built-in templating.
-- Using a consistent format for commenting on issues and pull requeests.
-- Replace variables in committed files, issues, prs, comments, wiki pages.
+## Use Cases 💡
 
-## Workflow Inputs
+- **Dynamic Content Creation**: Build customized Issue or PR descriptions beyond
+  GitHub's built-in templating
+- **Consistent Formatting**: Maintain a uniform style for comments on issues and
+  pull requests
+- **Variable Replacement**: Easily inject variables into any text content
+  (files, issues, PRs, comments, wiki pages)
 
-Provide the template as a file or direclty as text. If both are provided, the
-file will be ignored.
-
-| Input Name      | Description                                      | Required | Default |
-| --------------- | ------------------------------------------------ | -------- | ------- |
-| `template-file` | The path to a text file to load as the template. | No       | -       |
-| `template-text` | The template text with variable placeholders.    | No       | -       |
-| `template-vars` | An ENV style list or stringified JSON object.    | Yes      | -       |
-
-## Workflow Outputs
-
-After replacing variables in the template, the modified text is returned as an
-Action output. As such it can easily be referenced in subsequent steps.
-
-| Output Name    | Description                               |
-| -------------- | ----------------------------------------- |
-| `updated-text` | The text content with variables replaced. |
+## Basic Usage 🚀
 
-## Scenarios
-
-### Direct Text (JSON variables)
+### Direct Text with JSON Variables
 
 ```yaml
 steps:
@@ -50,7 +36,7 @@ steps:
     run: echo "${{ steps.build-comment.outputs.updated-text }}"
 ```
 
-### Direct Text (YAML variables)
+### Direct Text with YAML Variables
 
 ```yaml
 steps:
@@ -66,7 +52,28 @@ steps:
     run: echo "${{ steps.build-comment.outputs.updated-text }}"
 ```
 
-### Use template from same repository
+## Inputs ⚙️
+
+Provide the template as a file or directly as text. If both are provided, the
+file will be ignored.
+
+| Input Name      | Description                                      | Required |
+| --------------- | ------------------------------------------------ | -------- |
+| `template-file` | The path to a text file to load as the template. | No\*     |
+| `template-text` | The template text with variable placeholders.    | No\*     |
+| `template-vars` | An ENV style list or stringified JSON object.    | Yes      |
+
+\*One of either `template-file` or `template-text` must be provided.
+
+## Outputs 📤
+
+| Output Name    | Description                               |
+| -------------- | ----------------------------------------- |
+| `updated-text` | The text content with variables replaced. |
+
+## Examples 🔥
+
+### Use Template From Same Repository
 
 ```yaml
 steps:
@@ -87,7 +94,7 @@ steps:
     run: echo "${{ steps.build-comment.outputs.updated-text }}"
 ```
 
-### Use template from other repository
+### Use Template From Another Repository
 
 <!-- prettier-ignore-start -->
 ```yaml