diff --git a/README.md b/README.md
index 3c9af2d..55ad6f9 100644
--- a/README.md
+++ b/README.md
@@ -6,53 +6,104 @@ A RESTful API built with ASP.NET Core to manage a collection of historical wonde
 
 ## Features
 
-* **List all wonders:** Get a complete list of all wonders in the database.
-* **Get a specific wonder:** Retrieve a single wonder by its unique ID.
-* **Get a random wonder:** Fetch a random wonder.
-* **Create, Update, and Delete:** Full support for managing wonder entries.
-* **Structured Logging:** Captures detailed logs for requests, operations, and errors.
+- List all wonders
+- Get a specific wonder by ID
+- Get a random wonder
+- Create, Update, Delete operations
+- Structured logging and a small set of helper scripts for monitoring and testing
 
 ---
 
-## Usage
+## Quick start
 
-### Running the API
+From the project root (where `Ghaymah.WondersAPI.csproj` lives) you can run the API with the .NET SDK or inside Docker.
 
-Use the following command to launch the project. The API will be available at the URLs specified in the launch profile (e.g., `https://localhost:7247`).
+Run with the .NET SDK (requires .NET 8 SDK):
 
 ```bash
 dotnet run
 ```
 
-### Running Tests
-
-This project includes a test script. To execute the tests, run the following command from the root directory:
+Run inside Docker (uses the .NET 8 SDK image, maps container port 5004 to host 5004):
 
 ```bash
-dotnet test
+docker run -it --rm -p 5004:5004 -v "$(pwd):/app" -w /app mcr.microsoft.com/dotnet/sdk:8.0 dotnet run
 ```
 
----
+PowerShell note: if `$(pwd)` doesn't work in your environment, use `${PWD}` or the absolute path, for example:
 
-## API Endpoints
+```powershell
+docker run -it --rm -p 5004:5004 -v "${PWD}:/app" -w /app mcr.microsoft.com/dotnet/sdk:8.0 dotnet run
+```
 
-The base URL for all endpoints is `/api/wonders`.
+## Scripts
 
-| Method | Endpoint                    | Description                                |
-| :----- | :-------------------------- | :----------------------------------------- |
-| `GET`    | `/`                         | Retrieves a list of all wonders.           |
-| `GET`    | `/{id}`                     | Retrieves a single wonder by its ID.       |
-| `POST`   | `/`                         | Creates a new wonder.                      |
-| `PUT`    | `/{id}`                     | Updates an existing wonder.                |
-| `DELETE` | `/{id}`                     | Deletes a wonder by its ID.                |
-| `GET`    | `/random`                   | Retrieves a random wonder from the list.   |
+This repository includes two helper scripts used during development and testing:
 
+- `monitor.sh` — simple monitor script that forwards events to a monitoring endpoint
+- `test_api.sh` — basic API test runner that consumes `test_cases.json`
 
-#### Example: Create a new wonder
+### monitor.sh
 
-`POST /api/wonders`
+Usage:
 
-**Request Body:**
+```bash
+./monitor.sh <ghaymah-monitoring-endpoint-url>
+```
+
+Example:
+
+```bash
+./monitor.sh https://example.com/ingest
+```
+
+On Windows, run `monitor.sh` from WSL, Git Bash, or adapt it to PowerShell (e.g., use `Invoke-RestMethod`).
+
+### test_api.sh
+
+Usage (POSIX shells / Git Bash / WSL):
+
+```bash
+BASE_URL='http://localhost:5004' ./test_api.sh test_cases.json
+```
+
+PowerShell examples:
+
+Set environment variable for the session and run the script:
+
+```powershell
+$env:BASE_URL = 'http://localhost:5004'
+./test_api.sh test_cases.json
+```
+
+Or invoke using bash from PowerShell if the script requires bash:
+
+```powershell
+bash -c "BASE_URL='http://localhost:5004' ./test_api.sh test_cases.json"
+```
+
+## API Documentation (Swagger)
+
+When the API is running the Swagger UI is available at:
+
+```
+http://localhost:5004/docs
+```
+
+If your launch configuration or production mapping differs, adjust the host and port accordingly.
+
+## Endpoints
+
+Base route: `/api/wonders`
+
+- GET /api/wonders — list all wonders
+- GET /api/wonders/{id} — get a wonder by id
+- POST /api/wonders — create a new wonder
+- PUT /api/wonders/{id} — update a wonder
+- DELETE /api/wonders/{id} — delete a wonder
+- GET /api/wonders/random — get a random wonder
+
+Example create request:
 
 ```json
 {
@@ -65,27 +116,30 @@ The base URL for all endpoints is `/api/wonders`.
 }
 ```
 
-**Success Response (`201 Created`):**
+## Included files
 
-The API will return the newly created wonder object, including its server-generated ID.
+- `monitor.sh` — monitoring helper script
+- `test_api.sh` — test runner script
+- `test_cases.json` — test definitions used by `test_api.sh`
+- `seed-data.json` — sample data used for seeding
+- `appsettings.json` / `appsettings.Development.json` — configuration files
 
-```json
-{
-  "id": 1,
-  "name": "Great Pyramid of Giza",
-  "country": "Egypt",
-  "era": "Ancient",
-  "type": "Tomb",
-  "description": "The oldest and largest of the three pyramids in the Giza pyramid complex.",
-  "discoveryYear": -2560
-}
-```
+## Logs
 
----
+Log files are output to the `Logs/` folder (e.g. `Logs/api.log`) as configured in `appsettings.json`.
 
-## Technologies Used 🔧
+## GitPasha repository URL
 
-* **Framework:** ASP.NET Core 8
-* **Architecture:** RESTful API with standard controller patterns
+Replace the placeholder with your repository URL hosted on GitPasha:
 
----
+https://gitpasha.example.com/your-username/ghaymah-log-monitoring-project
+
+## Troubleshooting
+
+- If `dotnet run` fails, confirm .NET 8 SDK is installed: `dotnet --list-sdks`.
+- If Docker fails, ensure Docker Desktop is running and the mounted path is available in Docker.
+- On Windows, use WSL or Git Bash for shell scripts, or convert scripts to PowerShell.
+
+## License
+
+Add your license here.