From 4593e4a10cdf617e8b40ff31b68e7618cf2327d0 Mon Sep 17 00:00:00 2001
From: Even Stensberg <evenstensberg@gmail.com>
Date: Mon, 17 Aug 2026 12:48:19 +0200
Subject: [PATCH] docs(root): improve docs a bit (#2718)

---
 README.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 56 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index f74b78a5b8..c1e41c30a3 100755
--- a/README.md
+++ b/README.md
@@ -12,11 +12,30 @@ CyberChef is a simple, intuitive web app for carrying out all manner of "cyber"
 
 The tool is designed to enable both technical and non-technical analysts to manipulate data in complex ways without having to deal with complex tools or algorithms. It was conceived, designed, built and incrementally improved by an analyst in their 10% innovation time over several years.
 
+## Contents
+
+- [Official website](#official-website)
+- [Running Locally](#running-locally)
+  - [With Docker](#with-docker)
+  - [From source](#from-source)
+- [How it works](#how-it-works)
+- [Features](#features)
+- [Deep linking](#deep-linking)
+- [Browser support](#browser-support)
+- [Node.js support](#nodejs-support)
+- [Security](#security)
+- [Contributing](#contributing)
+- [Licencing](#licencing)
+
 ## Official website
 
 [CyberChef's official website can be found here][1] - have fun!
 
-## Running Locally with Docker
+## Running Locally
+
+You can run CyberChef with Docker (no toolchain required) or build it from source with Node.js.
+
+### With Docker
 
 **Prerequisites**
 
@@ -46,7 +65,41 @@ docker run -it -p 8080:8080 ghcr.io/gchq/cyberchef:latest
 
 Just like before, navigate to `http://localhost:8080` in your browser.
 
-This image is built and published through our [GitHub Workflows](.github/workflows/releases.yml)
+This image is built and published through our [GitHub Workflows](.github/workflows/releases.yml).
+
+### From source
+
+If you want to develop CyberChef or run it without Docker, you can build it directly with Node.js.
+
+**Prerequisites**
+
+- [Node.js](https://nodejs.org/) `v24` (see [Node.js support](#nodejs-support))
+
+
+> [!NOTE] 
+
+> You can use [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions and use the current development version in [this project](./.nvmrc) to avoid conflicts with other projects on your machine.
+
+**Setup**
+
+```bash
+git clone https://github.com/gchq/CyberChef.git
+cd CyberChef
+npm install
+```
+
+**Common tasks**
+
+| Command | Description |
+| --- | --- |
+| `npm start` | Run the development server with live reload at `http://localhost:8080`. |
+| `npm run build` | Produce a production build in the `build/prod` directory. |
+| `npm test` | Run the Node.js and operation test suites. |
+| `npm run testui` | Run the browser (UI) tests. |
+| `npm run lint` | Check the code against the linting rules. |
+| `npm run newop` | Scaffold a new operation via the interactive quickstart script. |
+
+If you hit an out-of-memory error while building large recipes, increase Node's heap size with `npm run setheapsize`.
 
 ## How it works
 
@@ -117,7 +170,7 @@ CyberChef is built to support
 
 ## Node.js support
 
-CyberChef is built to fully support Node.js `v24`. For more information, see the ["Node API" wiki page](https://github.com/gchq/CyberChef/wiki/Node-API)
+CyberChef is built to fully support Node.js `v24`. For more information, see the ["Node API" wiki page](https://github.com/gchq/CyberChef/wiki/Node-API).
 
 
 ## Security