diff --git a/README.md b/README.md
index f86b00c..fe44a28 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,47 @@
-# INFO for TFGrid
+<h1> TFGrid Docs</h1>
 
-> todo: kristof some content does not belong here, move to other repo
+<h2>Table of Contents</h2>
 
-## To preview new changes on local browser
+- [Overview](#overview)
+- [Basic Hero mdbook Commands](#basic-hero-mdbook-commands)
+- [Install and Use Hero](#install-and-use-hero)
+- [Create a new mdbook](#create-a-new-mdbook)
+- [Notes for Repo Owners](#notes-for-repo-owners)
 
-1. Pull new changes from local
+## Overview
 
-(please make sure commit / save your local changes first )
+This repository contains TFGrid docs in the form of mdbooks generated with the [Hero](https://github.com/freeflowuniverse/crystallib/tree/development/cli/hero) tool.
 
-hero mdbook -u https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript/nameofyourbook -gp
+To see the whole list of books, check the [heroscript directory](./heroscript).
 
-2. Build the book locally
+## Basic Hero mdbook Commands
 
-hero mdbook -u https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript/nameofyourbook
+Once Hero is set on your machine, you can run the following commands to preview mdbooks on your local browser:
 
-3. Preview on web browser
+- Pull new changes
+    ```
+    hero mdbook -u https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript/nameofyourbook -gp
+    ```
 
-hero mdbook -u https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript/nameofyourbook -o
\ No newline at end of file
+- Build the book
+    ```
+    hero mdbook -u https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript/nameofyourbook
+    ```
+- Preview on a web browser
+    ```
+    hero mdbook -u https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript/nameofyourbook -o
+    ```
+
+> Note: You can use -p instead of -u and set a path to your heroscript directory, as explained in the [docs](./docs).
+
+## Install and Use Hero
+
+To install and use Hero on a full VM running on the grid, read the [full VM guide](./docs/hero_fullvm.md).
+
+## Create a new mdbook 
+
+To create a new mdbook, read the [mdbook creation guide](./docs/hero_create_mdbooks.md).
+
+## Notes for Repo Owners
+
+> todo: kristof some content does not belong here, move to other repo
\ No newline at end of file