diff --git a/README.md b/README.md
index 98670ef..fbddd8a 100644
--- a/README.md
+++ b/README.md
@@ -1,53 +1,79 @@
-# Table of Contents
+# range42-api-definitions
 
-- [Project Overview](#Project-Overview)
-- [Repository Content](#Repository-Content)
-- [Contributing](#Contributing)
-- [License](#License)
+OpenAPI specification for the CR42 backend API (`CR42 - API`, version `v0.1`).
 
 ---
 
-# Project Overview
+## Contents
 
-**RANGE42** is a modular cyber range platform designed for real-world readiness.
-We build, deploy, and document offensive, defensive, and hybrid cyber training environments using reproducible, infrastructure-as-code methodologies.
+| File | Description |
+|------|-------------|
+| `openapi.json` | Machine-readable OpenAPI 3.x specification (used by Kong and tooling) |
+| `openapi.json.pretty` | Human-readable formatted copy of the same spec |
 
-## What we build
+---
+
+## API Summary
+
+**80 endpoints**, all under the `/v0/admin/` prefix.
+
+| Route group | Endpoints | Description |
+|-------------|-----------|-------------|
+| `/v0/admin/proxmox/vms/` | 25 | VM lifecycle: create, clone, delete, start, stop, pause, resume, bulk operations, config queries |
+| `/v0/admin/proxmox/vms/.../snapshot/` | 10 | Per-VM snapshot management: list, create, delete, revert |
+| `/v0/admin/run/bundles/` | 30 | Run named bundles: Ubuntu package installs, user setup, Proxmox VM provisioning (admin / vuln / student roles) |
+| `/v0/admin/run/scenarios/` | 1 | Run a named scenario by name |
+| `/v0/admin/proxmox/firewall/` | 12 | Firewall rules and aliases at VM, node, and datacenter scope |
+| `/v0/admin/proxmox/network/` | 6 | Network interface management on VMs and nodes |
+| `/v0/admin/proxmox/storage/` | 4 | Storage listing, ISO listing, template listing, ISO download |
+| `/v0/admin/debug/` | 2 | Health check (`ping`) and functional test (`func_test`) |
+
+---
+
+## How to Use
 
-- Proxmox-based cyber ranges with dynamic catalog 
-- Ansible roles for automated deployments (Wazuh, Kong, Docker, etc.)
-- Private APIs for range orchestration and telemetry
-- Developer and testing toolkits and JSON transformers for automation pipelines
-- ...
+### Browse via Swagger UI
 
-## Repository Overview
+When the `range42-backend-api` service is running locally, the interactive Swagger UI is available at:
 
-- **RANGE42 deployer UI** : A web interface to visually design infrastructure schemas and trigger deployments.
-- **RANGE42 deployer backend API** : Orchestrates deployments by executing playbooks and bundles from the catalog.
-- **RANGE42 catalog** : A collection of Ansible roles and Docker/Docker Compose stacks, forming deployable bundles.
-- **RANGE42 playbooks** : Centralized playbooks that can be invoked by the backend or CLI.
-- **RANGE42 proxmox role** : An Ansible role for controlling Proxmox nodes via the Proxmox API.
-- **RANGE42 devkit** : Helper scripts for testing, debugging, and development workflows.
-- **RANGE42 kong API gateway** : A network service in front of the backend API, handling authentication, ACLs, and access control policies.
-- **RANGE42 swagger API spec** : OpenAPI/Swagger JSON definition of the backend API.
+```
+http://<backend-host>:<port>/docs
+```
 
-### Putting it all together
+The raw OpenAPI JSON is served at:
 
-These repositories provide a modular and extensible platform to design, manage and deploy infrastructures automatically  either from the UI (coming soon) or from the CLI through the playbooks repository.
+```
+http://<backend-host>:<port>/openapi.json
+```
+
+### Kong gateway bootstrap
+
+Kong reads `openapi.json` to auto-configure its routes and upstream services. Point Kong's deck/sync configuration at this file to keep the gateway in sync with the current spec.
 
 ---
 
-# Repository Content
+## Regenerating the Spec
+
+The spec is generated directly from the running `range42-backend-api` application. From the root of that repo:
+
+```bash
+PYTHONPATH=. python -c "
+import json
+from app.main import create_app
+print(json.dumps(create_app().openapi(), indent=2))
+" > openapi.json
+```
 
-This repository contains the OpenAPISwagger JSON specification for the backend API used by the deployer UI and behind the kong API gateway : handling authentication, ACLs, and access control policies.
+Then copy the result here and update `openapi.json.pretty` with the formatted version.
+
+---
 
 ## Contributing
 
-This is a collaborative initiative, developed for applied security training, community integration, and internal capability building.
-We use centralized community health files in Range42 community health.
+This is a collaborative initiative developed for applied security training, community integration, and internal capability building.
+We use centralized community health files in the [Range42 community health](https://github.com/range42/.github) repository.
 
 ## License
 
-- GPL-3.0 license
-
+GPL-3.0 — see [LICENSE](LICENSE).