Update README.md for improved clarity and structure

- Revised project description to better highlight the purpose and features of the OpenStack Watcher dashboard.
- Added a table of contents for easier navigation.
- Expanded the features section to detail capabilities such as cluster overview, CPU & RAM usage, VM statistics, and audit recommendations.
- Clarified instructions regarding the `clouds.yaml` configuration file and its security implications.
- Improved formatting and consistency throughout the document.

README.md

@@ -1,11 +1,37 @@
-# watcher-visio
+# Watcher Visio
 
-Web dashboard (**SWatcher**) for monitoring an OpenStack cluster and visualising OpenStack Watcher audits: region and host counts, physical/virtual CPU and RAM usage, VM stats, top flavors, and audit recommendations (migrations) with CPU load charts per host.
+**OpenStack Watcher dashboard — monitor your cluster and visualise audit recommendations.**
 
-Data sources:
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![Django 5.2](https://img.shields.io/badge/django-5.2-green.svg)](https://www.djangoproject.com/)
 
-- **OpenStack** (SDK, `clouds.yaml`): compute region, servers, flavors; Watcher API for audits, action plans, and actions.
+SWatcher is a web dashboard for OpenStack operators. It shows region and host counts, physical/virtual CPU and RAM usage, VM statistics, top flavors, and OpenStack Watcher audit results with migration recommendations and CPU load charts per host. Data is pulled from OpenStack (SDK and Watcher API) and Prometheus (node_exporter, libvirt, placement metrics).
-- **Prometheus**: node_exporter, libvirt, and placement metrics for pCPU/vCPU, pRAM/vRAM, and VM counts.
+
+---
+
+## Table of contents
+
+- [Features](#features)
+- [Configuration](#configuration)
+- [Running locally](#running-locally)
+- [Running with Docker](#running-with-docker)
+- [Frontend build](#frontend-build)
+- [API](#api)
+- [Project structure](#project-structure)
+- [Architecture](#architecture)
+- [Running tests](#running-tests)
+
+---
+
+## Features
+
+- **Cluster overview** — compute region name, total hosts, and aggregate resource usage
+- **CPU & RAM** — physical and virtual CPU/RAM usage and overcommit ratios (from Prometheus)
+- **VM statistics** — total and active VM counts
+- **Top flavors** — most used OpenStack flavors
+- **Watcher audits** — list of audits with action plans and migration recommendations
+- **CPU load charts** — per-host current and projected CPU load for audit actions (Chart.js)
+- **Mock mode** — `USE_MOCK_DATA=true` for local development without OpenStack or Prometheus
 
 ---
 
@@ -27,7 +53,7 @@ Defaults for Prometheus and OpenStack are in [watcher_visio/settings.py](watcher
 
 ### OpenStack (`clouds.yaml`)
 
-Authentication uses OpenStack’s standard `clouds.yaml`. The cloud name must match `OPENSTACK_CLOUD`. Place `clouds.yaml` in the project root (or standard OpenStack config location). **Do not commit real credentials;** use a local or CI-specific file and keep production secrets out of the repo.
+Authentication uses OpenStack’s standard `clouds.yaml`. The cloud name must match `OPENSTACK_CLOUD`. Place `clouds.yaml` in the project root (or standard OpenStack config location). Do not commit real credentials; use a local or CI-specific file and keep production secrets out of the repo.
 
 ---
 
@@ -98,14 +124,14 @@ Source: [static/css/main.css](static/css/main.css). Output: `static/css/output.c
 
 ---
 
-## Repository structure
+## Project structure
 
 | Path | Description |
 |------|-------------|
 | `watcher_visio/` | Django project: settings, root URL config, WSGI/ASGI. |
 | `dashboard/` | Main app: views (index, api_stats, api_audits), `openstack_utils` (connect, flavor, audits), `prometheus_utils` (query), `mock_data`, `templatetags` (mathfilters), tests. |
 | `templates/`, `static/` | HTML templates and static assets (Tailwind output, Chart.js, etc.). |
-| `clouds.yaml` | OpenStack config (do not commit production secrets). |
+| Optional: `clouds.yaml` in project root | OpenStack config; not in repo — do not commit production secrets. |
 | [Dockerfile](Dockerfile), [docker-entrypoint.sh](docker-entrypoint.sh) | Image build and entrypoint (migrate then run server). |
 | [docker-compose.yml](docker-compose.yml), [docker-compose.dev.yml](docker-compose.dev.yml) | Compose: base (prod-like) and dev override (mount + mock). |
 
@@ -168,4 +194,4 @@ Use the **dev** compose file so the project directory is mounted; the container
 docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm watcher-visio python3 manage.py test dashboard
 ```
 
-If you run tests with only the base compose (`docker compose run --rm watcher-visio ...`), the container uses the code baked into the image at build time. After code or test changes, either rebuild the image or use the dev override above so tests see the latest files.
+With the base compose only, the container uses the code baked into the image at build time. After code or test changes, either rebuild the image or use the dev override above so tests see the latest files.