diff --git a/.github/workflows/bench.yml b/.github/workflows/bench.yml
index f30934c803..9572e6a7f2 100644
--- a/.github/workflows/bench.yml
+++ b/.github/workflows/bench.yml
@@ -45,3 +45,13 @@ jobs:
         alert-comment-cc-users: '@unbalancedparentheses'
     - name: Clean benches
       run: make clean
+
+    - name: Build rustdoc
+      run: cargo doc --no-deps --workspace
+
+    - name: Deploy rustdoc to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./target/doc
+        destination_dir: docs
diff --git a/README.md b/README.md
index d701bad50a..b78c366543 100644
--- a/README.md
+++ b/README.md
@@ -298,37 +298,7 @@ Cairo-vm offers a tracer which gives you a visualization of how your memory and
 
 ## 📊 Benchmarks
 
-Running a [Cairo program](./cairo_programs/benchmarks/big_fibonacci.cairo) that gets the 1.5 millionth Fibonacci number we got the following benchmarks:
-
-- Execution time with [Criterion](./docs/benchmarks/criterion_benchmark.pdf)
-- [Flamegraph](./docs/benchmarks/flamegraph.svg)
-- Github action [results](https://lambdaclass.github.io/cairo-vm/)
-
-Note before running the benchmark suite: the benchmark named [iai_benchmark](https://github.com/lambdaclass/cairo-vm/blob/8dba86dbec935fa04a255e2edf3d5d184950fa22/Cargo.toml#L59) depends on Valgrind. Please make sure it is installed prior to running the `iai_benchmark` benchmark.
-
-Run the complete benchmark suite with cargo:
-
-```bash
-cargo bench
-```
-
-Run only the `criterion_benchmark` benchmark suite with cargo:
-
-```bash
-cargo bench --bench criterion_benchmark
-```
-
-Run only the `iai_benchmark` benchmark suite with cargo:
-
-```bash
-cargo bench --bench iai_benchmark
-```
-
-Benchmark the `cairo-vm` in a hyper-threaded environment with the [`examples/hyper_threading/ crate`](examples/hyper_threading/)
-```bash
-make hyper-threading-benchmarks
-```
-
+Benchmark results are available in [docs/benchmarks/criterion_benchmark.pdf](docs/benchmarks/criterion_benchmark.pdf) and [docs/benchmarks/flamegraph.svg](docs/benchmarks/flamegraph.svg).
 
 ## 📜 Changelog
 
@@ -357,6 +327,8 @@ You can find more detailed instructions in the [CONTRIBUTING.md](CONTRIBUTING.md
 
 ## 📚 Documentation
 
+See [docs/README.md](docs/README.md) for extended documentation, including architecture, usage, and developer guides.
+
 ### Cairo
 
 - From Cairo Documentation: [How Cairo Works](https://docs.cairo-lang.org/how_cairo_works/index.html)
diff --git a/docs/README.md b/docs/README.md
index c781d4d706..af8f3e8325 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,8 +1,10 @@
 # Documentation
 
+This folder contains extended documentation for Cairo VM. For a general overview, see the [main README](../README.md).
+
 * [How does the Cairo VM work?](./vm/)
 * [How does the original Cairo VM work?](./python_vm/)
-* [Benchmarks](./benchmarks/)
+* [Benchmarks](./benchmarks/) ([see results](./benchmarks/criterion_benchmark.pdf), [flamegraph](./benchmarks/flamegraph.svg))
 * [Custom Hint Processor](./hint_processor/)
 * [How to run a cairo program with custom hints](./hint_processor/builtin_hint_processor)
 * [References parsing](./references_parsing/)
diff --git a/docs/vm/README.md b/docs/vm/README.md
index f340a4b8c2..f4d3bbf853 100644
--- a/docs/vm/README.md
+++ b/docs/vm/README.md
@@ -2,6 +2,8 @@
 
 # How does the Cairo VM work?
 
+> For a general overview, see the [main README](../../README.md). For the documentation structure, see [docs/README.md](../README.md).
+
 ## High Level Overview
 
 The Cairo virtual machine is meant to be used in the context of STARK validity proofs. What this means is that the point of Cairo is not just to execute some code and get a result, but to *prove* to someone else that said execution was done correctly, without them having to re-execute the entire thing. The rough flow for it looks like this:
diff --git a/vm/Cargo.toml b/vm/Cargo.toml
index 84cda21268..b6ea085c3f 100644
--- a/vm/Cargo.toml
+++ b/vm/Cargo.toml
@@ -82,6 +82,7 @@ clap = { version = "4.3.10", features = ["derive"], optional = true}
 assert_matches = "1.5.0"
 rstest = { version = "0.17.0", default-features = false }
 num-prime = { version = "0.4.3", features = ["big-int"] }
+aquamarine = "0.7"
 
 [target.'cfg(target_arch = "wasm32")'.dev-dependencies]
 wasm-bindgen-test = "0.3.50"
diff --git a/vm/src/lib.rs b/vm/src/lib.rs
index 425a5796fd..e6770d3f90 100644
--- a/vm/src/lib.rs
+++ b/vm/src/lib.rs
@@ -1,4 +1,23 @@
-//! # An implementation of the Cairo virtual machine
+//! # Cairo VM
+//!
+//! This crate provides a fast and safe implementation of the Cairo virtual machine in Rust.
+//!
+//! - [Project README](https://github.com/lambdaclass/cairo-vm/blob/main/README.md)
+//! - [Extended documentation](https://github.com/lambdaclass/cairo-vm/blob/main/docs/README.md)
+//!
+//! ## Features
+//! - STARK-friendly execution trace
+//! - Custom hint processor support
+//! - Tracing and debugging tools
+//!
+//! ## Example
+//! ```rust
+//! use cairo_vm::vm::vm_core::VirtualMachine;
+//! // ... usage example ...
+//! ```
+//!
+//! ## Diagrams
+//! Mermaid diagrams are supported in rustdoc via the `aquamarine` dependency.
 //!
 //! ## Feature Flags
 //! - `std`: Enables usage of the [`std`] standard library. Enabled by default.