From 6415107ca7030f958de4b043503434b8bbdef61b Mon Sep 17 00:00:00 2001
From: andreatp <andrea.peruffo1982@gmail.com>
Date: Wed, 4 Nov 2026 17:19:13 +0000
Subject: [PATCH 1/6] docs: fix stale and incorrect statements

SIMD is interpreter-only: the bytecode compilers fail on v128, so the
Quick Start requirement and the SIMD page overstated support. The
compiler pages claimed parity with the interpreter's spec tests, which
no longer holds. Also remove a dangling example reference in Linking,
a license link pointing at a page without licenses, a copy-pasted
stdout redirect, and release-time phrasing elsewhere. Add writing
rules to the docs README.
---
 docs/README.md                             |  9 +++++++++
 docs/docs/advanced/memory-customization.md |  4 ----
 docs/docs/advanced/simd.md                 | 14 +++-----------
 docs/docs/advanced/tools.md                |  3 +--
 docs/docs/core/linking.md                  |  5 ++---
 docs/docs/execution/build-time-compiler.md |  9 +++------
 docs/docs/execution/runtime-compiler.md    | 13 ++++---------
 docs/docs/index.md                         |  2 +-
 docs/docs/security/best-practices.md       |  2 +-
 docs/docs/wasi/index.md                    |  4 +---
 10 files changed, 25 insertions(+), 40 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index 9d6cc86a6..1bba3401b 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -24,3 +24,12 @@ $ npm run build
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
+
+### Writing docs
+
+- Describe how to use a feature, not how it is implemented. Internals belong in Javadoc or in the pull request description.
+- No release-time or migration statements. Those go in a blog post; breaking changes relative to Chicory go in the migration guide.
+- One code sample per option. Show a builder once per page.
+- Body headings start at `##`; the frontmatter `title` is the page heading. Open every page with one plain sentence saying what it covers, which becomes its description in `llms.txt`.
+- Names: Wasm, interpreter, runtime compiler, build-time compiler. Version placeholder: `${endive.version}`.
+- Every page is executed by `npm test`: keep the hidden `//DEPS` and `docs.FileOps.writeResult(...)` blocks, and update `tests/approvals/` when a page moves.
diff --git a/docs/docs/advanced/memory-customization.md b/docs/docs/advanced/memory-customization.md
index 3f6db6850..29b6c4813 100644
--- a/docs/docs/advanced/memory-customization.md
+++ b/docs/docs/advanced/memory-customization.md
@@ -10,10 +10,6 @@ title: Advanced Wasm Memory Customization
 
 docs.FileOps.copyFromWasmCorpus("count_vowels.rs.wasm", "count_vowels.rs.wasm");
 
-System.setOut(new PrintStream(
-  new BufferedOutputStream(
-    new FileOutputStream("docs/examples/rust.md.result"))));
-
 import run.endive.wasm.Parser;
 import run.endive.runtime.Instance;
 import run.endive.runtime.ByteArrayMemory;
diff --git a/docs/docs/advanced/simd.md b/docs/docs/advanced/simd.md
index c3387e4f3..d401519d9 100644
--- a/docs/docs/advanced/simd.md
+++ b/docs/docs/advanced/simd.md
@@ -4,22 +4,14 @@ sidebar_label: SIMD
 title: SIMD support
 ---
 
-SIMD is supported out of the box by the interpreter.
+SIMD (`v128`) instructions are supported by the interpreter on every supported JDK, with no extra dependency or configuration.
 
-All WebAssembly `v128` instructions use the scalar interpreter implementation on every supported
-JDK. No extra dependency, JVM flag, or machine-factory configuration is required.
+The runtime and build-time compilers do not support SIMD: compiling a module that uses `v128` instructions fails, so such modules must run in the interpreter.
 
 :::warning
-SIMD support **REQUIRES** validation. Disabling validation (`WasmModule.builder().withValidation(false)`) is likely to produce incorrect results.
+SIMD execution relies on validation. Keep it enabled (the default) for modules that use `v128`.
 :::
 
-### Migration
-
-The `run.endive:simd` module is gone. If your application declares it and uses
-`SimdInterpreterMachine`, remove that dependency and the explicit
-`withMachineFactory(SimdInterpreterMachine::new)` call; the default machine from
-`run.endive:runtime` now executes `v128` instructions.
-
 <!--
 ```java
 //DEPS run.endive:docs-lib:999-SNAPSHOT
diff --git a/docs/docs/advanced/tools.md b/docs/docs/advanced/tools.md
index d7f1e4a4b..662f50fc5 100644
--- a/docs/docs/advanced/tools.md
+++ b/docs/docs/advanced/tools.md
@@ -49,8 +49,7 @@ System.setOut(new PrintStream(
 
 ## wat2wasm
 
-In Endive, we don't have a Wasm text format parser just yet.
-To overcome this limitation you can use `wat2wasm`, for example:
+Endive does not parse the Wasm text format. Use `wat2wasm` to convert text to binary:
 
 ```java
 import run.endive.wabt.Wat2Wasm;
diff --git a/docs/docs/core/linking.md b/docs/docs/core/linking.md
index 1635c7bd6..99b7a698e 100644
--- a/docs/docs/core/linking.md
+++ b/docs/docs/core/linking.md
@@ -71,9 +71,8 @@ For instance, the exported function `logIt` will be visible by other modules as
 
     However, in most cases we recommend to use the shorthand form.
 
-- Also notice that registering two instances with the same name results in overwriting the
-functions, globals, memories, tables with matching names. In this case, the new `logger2.logIt` function
-overwrote the old `logger2.logIt` function.
+- Registering a second instance under a name already in use overwrites the functions, globals,
+memories and tables with matching names.
 
 - The current `Store` is a mutable object, not meant to be shared (it is not thread-safe).
 
diff --git a/docs/docs/execution/build-time-compiler.md b/docs/docs/execution/build-time-compiler.md
index 71f3fe790..298415e7a 100644
--- a/docs/docs/execution/build-time-compiler.md
+++ b/docs/docs/execution/build-time-compiler.md
@@ -9,12 +9,9 @@ title: Build Time Compilation
 The compiler translates Wasm to JVM bytecode without post-compilation verification. Only compile Wasm modules you trust. See [Security Model](/docs/security/overview).
 :::
 
-The build time compiler backend is a drop-in replacement for the interpreter, and it passes 100% of the same 
-spec tests that the interpreter already supports.
-
-This compiler translates the WASM instructions to Java bytecode and stores them as `.class` files
-that you package in your application.  The resulting code is usually expected to evaluate (much) faster and 
-consume less memory than if it was interpreted.
+The build-time compiler translates Wasm functions to JVM bytecode and stores them as `.class` files
+that you package in your application. Compiled code runs much faster and uses less memory than interpreted code.
+Modules that use SIMD (`v128`) instructions cannot be compiled and must run in the interpreter.
 
 The build time compiler has several advantages over the [Runtime Compiler](runtime-compiler.md) such as: 
 
diff --git a/docs/docs/execution/runtime-compiler.md b/docs/docs/execution/runtime-compiler.md
index a27b8eef8..622f9b9f7 100644
--- a/docs/docs/execution/runtime-compiler.md
+++ b/docs/docs/execution/runtime-compiler.md
@@ -13,16 +13,11 @@ The compiler translates Wasm to JVM bytecode without post-compilation verificati
 Compiling very large Wasm modules can consume significant memory and CPU. Consider setting JVM heap limits and compilation timeouts when processing untrusted input.
 :::
 
-The runtime compiler backend is a drop-in replacement for the interpreter, and it passes 100% of the same
-spec tests that the interpreter already supports.
+The runtime compiler translates Wasm functions to JVM bytecode in memory when the instance is created, as a drop-in replacement for the interpreter.
+Compiled code runs much faster and uses less memory than interpreted code, at the cost of a small delay at instantiation.
+Use the [build-time compiler](./build-time-compiler.md) to move that work into your build.
 
-This runtime compiler translates the WASM instructions to Java bytecode on-the-fly in-memory.
-The resulting code is usually expected to evaluate (much) faster and consume less memory than if it 
-was interpreted.
-
-At the current time, the compiler will eagerly compile all WASM instructions to Java bytecode.  You end up
-paying a small performance penalty at Instance initialization, but the execution speedup
-is usually worth it.  Use [Build Time Compilation](./build-time-compiler.md) if you want to avoid the penalty.
+Modules that use SIMD (`v128`) instructions cannot be compiled and must run in the interpreter.
 
 ## Using
 
diff --git a/docs/docs/index.md b/docs/docs/index.md
index 388014756..33b7047eb 100644
--- a/docs/docs/index.md
+++ b/docs/docs/index.md
@@ -5,7 +5,7 @@ title: Quick start
 ---
 
 :::info[Requirements]
-Endive requires **Java 11** or later. SIMD instructions are supported on all supported Java versions.
+Endive requires **Java 11** or later.
 :::
 
 ### Install the dependency
diff --git a/docs/docs/security/best-practices.md b/docs/docs/security/best-practices.md
index 4b0d0c671..cb2340988 100644
--- a/docs/docs/security/best-practices.md
+++ b/docs/docs/security/best-practices.md
@@ -86,7 +86,7 @@ The runtime and build-time compilers translate Wasm to JVM bytecode for performa
 
 ## Dependency Supply Chain
 
-- All Endive dependencies are checked against the [Bytecode Alliance allowed license list](/docs/security/overview) in CI
+- All Endive dependencies are checked in CI against the Bytecode Alliance allowed license list
 - Dependency vulnerabilities are scanned nightly via OWASP Dependency-Check
 - Dependabot is enabled for automated security updates
 - All dependency updates are manually reviewed before merging
diff --git a/docs/docs/wasi/index.md b/docs/docs/wasi/index.md
index 55b74a203..258810a3c 100644
--- a/docs/docs/wasi/index.md
+++ b/docs/docs/wasi/index.md
@@ -173,9 +173,7 @@ var wasi = WasiOptions.builder().
 
 ## disk
 
-We provide limited support for operations on the disk, we only test on a Virtual FileSystem and we encourage you to use the same. We use [Google's Jimfs](https://github.com/google/jimfs).
-
-Example code to use the disk looks like:
+File access goes through a virtual file system, which confines the guest to the directories you map. The example uses [Google's Jimfs](https://github.com/google/jimfs):
 
 <!--
 ```java

From 04df16c2bcf45d85772b3999b95b471961c67799 Mon Sep 17 00:00:00 2001
From: andreatp <andrea.peruffo1982@gmail.com>
Date: Wed, 4 Nov 2026 17:21:07 +0000
Subject: [PATCH 2/6] docs: trim the compiler pages to what users need

Cut the method naming contract (it lives in the MethodPrefixer
Javadoc), the three interpreter fallback samples, the Maven plugin
help dump, the cache file layout, and the host function preamble.
Each option is now a sentence or two and one builder sample.
---
 docs/docs/core/host-functions.md           |  43 ++----
 docs/docs/execution/build-time-compiler.md | 148 +++++----------------
 docs/docs/execution/compiler-cache.md      |  35 +----
 docs/docs/execution/runtime-compiler.md    | 134 ++++---------------
 4 files changed, 77 insertions(+), 283 deletions(-)

diff --git a/docs/docs/core/host-functions.md b/docs/docs/core/host-functions.md
index 8a905569b..3e9d41227 100644
--- a/docs/docs/core/host-functions.md
+++ b/docs/docs/core/host-functions.md
@@ -3,47 +3,22 @@ sidebar_position: 1
 sidebar_label: Host Functions
 title: Host Functions
 ---
-# Host and guests
+A host function is a Java function that a Wasm module imports and calls, and it is the way a module reaches anything outside its sandbox.
 
 :::warning[Security Consideration]
-Host functions cross the sandbox boundary. Validate all arguments received from Wasm code — especially memory offsets and lengths — before accessing host resources. Never trust guest-provided pointers without bounds checking. See [Security Best Practices](/docs/security/best-practices).
+Host functions cross the sandbox boundary: validate every argument that comes from Wasm, especially memory offsets and lengths, before touching host resources. See [Security Best Practices](/docs/security/best-practices).
 :::
 
-In Wasm, the instance of a module is generally regarded as the **guest**,
-and the surrounding runtime environment is called the **host**.
+In Wasm terms the module instance is the **guest** and the surrounding runtime, your Java application, is the **host**.
+A module can **export** functions for the host to call, and **import** functions that the host must provide when the module is instantiated.
+Without imports a module is pure compute: it cannot perform I/O or interact with other modules.
 
-For example, an **application** using Endive as a **library** would be the **host**
-to a Wasm module **guest** you have instantiated.
+## Writing a host function
 
-Wasm modules may **export** functions, so that they can be externally invoked.
-But Wasm modules may also **import** functions. 
-These imports have to be resolved at the time when a module is instantiated;
-in other words, when a module is instantiated, the runtime has to provide
-references for all the imports that a module declares.
+A host function is called from Wasm but runs in the JVM, so it can do anything your Java code can.
+That is also what makes it a security boundary when the module is untrusted.
 
-The import/export mechanism is the way through which Wasm interacts 
-with the outside world: without imports, a Wasm module is "pure compute",
-that is, it cannot perform any kind of I/O, nor can it interact with other
-modules.
-
-## Host Functions
-
-One way to fulfill imports is providing a **host function** written in Java. 
-No matter what source language that your Wasm module was written in, 
-it will be able to call this Java function when needed.
-
-It is called a **host** function because it is executed in the environment of the
-**host** (in this case, a JVM). As opposed to any other Wasm function, 
-a **host function** is _unrestricted_ and it may interact with the surrounding
-environment in any arbitrary way. This lets you effectively escape the sandbox.
-As a consequence, host functions are a security boundary and
-need to be implemented carefully if the Wasm code is not trusted.
-
-You can think of host functions as similar to OS system calls or the standard library in your favorite programming language.
-The key difference is that, instead of relying on a default implementation, you use Java to define their behavior 
-and determine what they do.
-
-Let's see it with another example. Download the following Wasm binary:
+Download the following module, which imports a `console.log` function:
 
 ```bash
 curl https://raw.githubusercontent.com/bytecodealliance/endive/main/wasm-corpus/src/main/resources/compiled/host-function.wat.wasm > logger.wasm
diff --git a/docs/docs/execution/build-time-compiler.md b/docs/docs/execution/build-time-compiler.md
index 298415e7a..27b892dd6 100644
--- a/docs/docs/execution/build-time-compiler.md
+++ b/docs/docs/execution/build-time-compiler.md
@@ -1,63 +1,26 @@
 ---
 sidebar_position: 2
-sidebar_label: Build time Compilation
-title: Build Time Compilation
+sidebar_label: Build-time Compiler
+title: Build-time Compiler
 ---
-## Overview
+
+The build-time compiler translates Wasm functions to JVM bytecode during your build and stores them as `.class` files that you package in your application.
 
 :::warning[Security Consideration]
-The compiler translates Wasm to JVM bytecode without post-compilation verification. Only compile Wasm modules you trust. See [Security Model](/docs/security/overview).
+The compiler generates JVM bytecode without a separate verification pass. Only compile modules you trust. See [Security Model](/docs/security/overview).
 :::
 
-The build-time compiler translates Wasm functions to JVM bytecode and stores them as `.class` files
-that you package in your application. Compiled code runs much faster and uses less memory than interpreted code.
-Modules that use SIMD (`v128`) instructions cannot be compiled and must run in the interpreter.
-
-The build time compiler has several advantages over the [Runtime Compiler](runtime-compiler.md) such as: 
-
-- improved instance initialization time: the translation occurs at build time
-- no reflection needed: easier to use with `native-image`
-- fewer runtime dependencies: ASM is only needed at build time
-- distribute Wasm modules as self-contained jars: making it a convenient way to distribute software that was not originally meant to run on the Java platform
-
-You can use the compiler at build-time via Maven plug-in, Gradle plug-in, or plain CLI.
-
-### Interpreter Fall Back
-
-The WASM to bytecode compiler translates each WASM function into JVM method.  Occasionally you will find WASM module where functions are bigger than the maximum method size allowed by the JVM.  In these rare cases, we fall back to executing these large functions in the interpreter.  
-
-Since interpreted functions have worse performance, we want to make sure you are aware this is happening so the build time compiler will FAIL if it finds any functions that are too large.  The build tool will produce a message that contains text like:
-
-```text
-WASM function size exceeds the Java method size limits and cannot be compiled to Java bytecode. It can only be run in the interpreter. Either reduce the size of the function or enable the interpreter fallback mode: WASM function index: 3938
-```
-
-If this happens you can configure your build tool, to just issue warning messages, or to be silent.  Another way to silence the message is to configure the build tool with an explicit list of functions that should be interpreted. Typically, you obtain the list of the functions by running the compiler once with `interpreterFallback` set to `WARN`
-
-### Method Names
-
-By default the compiler names each generated method `func_0`, `func_1`, etc. Set `methodPrefixer` to
-name them after the module's name section instead, so that thread dumps, profiler output and stack
-traces identify functions by name:
-
-```xml
-<configuration>
-  <wasmFile>src/main/resources/add.wasm</wasmFile>
-  <name>org.acme.wasm.Add</name>
-  <methodPrefixer>run.endive.compiler.NameSectionMethodPrefixer</methodPrefixer>
-</configuration>
-```
+Compared to the [runtime compiler](runtime-compiler.md):
 
-The names are resolved at build time and baked into the generated classes; the name section itself is
-not shipped with them.
+- nothing is compiled at instantiation
+- no reflection and no ASM at runtime, so it works with `native-image`
+- the module ships as a self-contained jar
 
-The parameter accepts any `run.endive.compiler.MethodPrefixer` with a public no-argument constructor,
-declared as a dependency of the plugin. See [Method Names](runtime-compiler.md#method-names) for the
-naming contract.
+Modules that use SIMD (`v128`) instructions cannot be compiled and must run in the interpreter.
 
-## Using Maven
+## Maven
 
-Example configuration of the Maven plug-in:
+Configure the plugin:
 
 ```xml
 <build>
@@ -84,7 +47,7 @@ Example configuration of the Maven plug-in:
 </build>
 ```
 
-In the codebase you can use the generated module by configuring appropriately the `MachineFactory`:
+Then use the generated class as the machine factory:
 
 <!--
 ```java
@@ -126,7 +89,26 @@ var instance = Instance.builder(module).
         build();
 ```
 
-### Generating Module Exports and Imports
+### Parameters
+
+The ones you are likely to set:
+
+| Parameter | Description |
+|---|---|
+| `wasmFile` | The Wasm module to compile. Required. |
+| `name` | Fully qualified name of the generated class. Required. |
+| `moduleInterface` | Fully qualified name for which to generate typed `_ModuleExports` and `_ModuleImports` wrappers. See [below](#generating-module-exports-and-imports). |
+| `interpreterFallback` | What to do with a function too large for a JVM method: `FAIL` (default), `WARN` or `SILENT`. With `WARN` or `SILENT` the function runs in the interpreter. |
+| `interpretedFunctions` | Comma-separated function indexes to interpret instead of compile. |
+| `methodPrefixer` | Set to `run.endive.compiler.NameSectionMethodPrefixer` to name the compiled methods after the module's name section, so stack traces and profiler output show the Wasm function names. Any `MethodPrefixer` with a public no-argument constructor on the plugin's classpath is accepted. |
+
+Print the full list with:
+
+```bash
+mvn help:describe -DgroupId=run.endive -DartifactId=endive-compiler-maven-plugin -Ddetail
+```
+
+### Generating module exports and imports
 
 The build-time compiler can also generate typed Java wrappers for a module's exports and imports,
 eliminating the need for the [`@WasmModuleInterface` annotation](../annotations/index.md#wasmmoduleinterface) and the annotation processor setup.
@@ -183,65 +165,7 @@ var instance = Instance.builder(DemoModule.load()).
 var exports = new Demo_ModuleExports(instance);
 ```
 
-### The `compile` Goal
-
-You can obtain the full description of the Maven Plugin with a command like:
-`mvn help:describe -DgroupId=run.endive -DartifactId=endive-compiler-maven-plugin -Dversion=999-SNAPSHOT -Ddetail`
-
-```
-endive:compile
-  Description: This plugin generates an invokable library from the compiled
-    Wasm
-  Implementation: run.endive.build.time.maven.EndiveCompilerGenMojo
-  Language: java
-  Bound to phase: generate-sources
-
-  Available parameters:
-
-    interpretedFunctions
-      The indexes of functions that should be interpreted, separated by commas
-
-    interpreterFallback (Default: FAIL)
-      Required: true
-      the action to take if the compiler needs to use the interpreter because a
-      function is too big
-
-    methodPrefixer
-      Fully qualified name of a MethodPrefixer implementation used to name the
-      compiled methods. Defaults to naming them func_0, func_1 and so on. Set
-      it to run.endive.compiler.NameSectionMethodPrefixer to name them after
-      the module's name section.
-
-    moduleInterface
-      Fully qualified name of the user's class for which to generate
-      _ModuleExports and _ModuleImports wrapper classes. When set, eliminates
-      the need for @WasmModuleInterface annotation and the annotation processor.
-
-    name
-      Required: true
-      the base name to be used for the generated classes
-
-    targetClassFolder (Default:
-    ${project.build.directory}/generated-resources/endive-compiler)
-      Required: true
-      the target folder to generate classes
-
-    targetSourceFolder (Default:
-    ${project.build.directory}/generated-sources/endive-compiler)
-      Required: true
-      the target source folder to generate the Machine implementation
-
-    targetWasmFolder (Default:
-    ${project.build.directory}/generated-resources/endive-compiler)
-      Required: true
-      the target wasm folder to generate the stripped meta wasm module
-
-    wasmFile
-      Required: true
-      the wasm module to be used
-```
-
-#### IDE shortcomings
+### IDE shortcomings
 
 In some IDEs the sources generated under the standard folder `target/generated-sources` are not automatically recognized.
 To overcome this limitation you can use an additional Maven Plugin for a smoother IDE experience:
@@ -267,10 +191,10 @@ To overcome this limitation you can use an additional Maven Plugin for a smoothe
 </plugin>
 ```
 
-## Using Gradle [community]
+## Gradle [community]
 
 Gradle users can leverage the [wasm2class-gradle-plugin](https://github.com/illarionov/wasm2class-gradle-plugin),
-a third-party plugin that serves as an alternative to the Maven plugin, running the AoT compiler at build time
+a third-party plugin that serves as an alternative to the Maven plugin, running the build-time compiler
 and enabling the use of pre-compiled Wasm code in Java, Kotlin, and Android projects.
 
 To set it up, make sure MavenCentral is listed as a repository in the `pluginManagement` block of your `settings.gradle.kts`:
diff --git a/docs/docs/execution/compiler-cache.md b/docs/docs/execution/compiler-cache.md
index 5cd44933d..87bd1f662 100644
--- a/docs/docs/execution/compiler-cache.md
+++ b/docs/docs/execution/compiler-cache.md
@@ -4,11 +4,9 @@ sidebar_label: Runtime Compiler Cache
 title: Runtime Compiler Cache
 ---
 
-# Overview of the Runtime Compiler Cache
+The compiler cache stores the bytecode produced by the [runtime compiler](runtime-compiler.md), so later runs skip compilation and start faster.
 
-The runtime compiler cache lets the Endive runtime compiler store the results of compiling WASM modules to Java bytecode. Subsequent executions can skip compilation and start faster.
-
-Use the experimental directory-based cache, or implement the simple `run.endive.compiler.Cache` interface:
+Use the experimental directory cache below, or implement the `run.endive.compiler.Cache` interface:
 
 ```java
 public interface Cache {
@@ -19,34 +17,15 @@ public interface Cache {
 
 The compiler uses the module digest (default SHA-256) as the cache key. For example, `"sha-256:KRgyTkCm43c34ksqtA8gmdDw4YCfquC2G0qfIFCpb+w="` could be a key. The cached value is a JAR containing the module's compiled bytecode.
 
-## The Directory Cache
+## The directory cache
 
 :::warning[Security Consideration]
-The directory cache stores compiled bytecode on disk without integrity verification. Ensure the cache directory has restrictive permissions (`chmod 700`) and is not writable by untrusted users. Do not share caches across trust boundaries.
+The cache stores bytecode on disk without integrity checks. Keep the directory private (`chmod 700`) and never share it across trust boundaries.
 :::
 
-The directory cache stores entries as files under a configured directory.   For example, 
-if the cache directory is `/cache`, and you store the following cache key: 
-
-`sha-256:KRgyTkCm43c34ksqtA8gmdDw4YCfquC2G0qfIFCpb+w=`
- 
-then that will create the following file: 
-
-`/cache/sha-256/kr/gytkcm43c34ksqta8gmddw4ycfquc2g0qfifcpb-w.jar` 
-
-It transforms the key to:
-* translate characters to be file-system-friendly
-* use a two-character subdirectory prefix to avoid directory scaling issues
-
-The implementation uses file system atomic moves (write to a temp file, then move to the final location). This makes the cache thread-safe and safe to share across processes and avoids partial-write failures. Temp files are written under `/cache/.tmp`. Partially written temp files may be left after a crash; there is no automatic cleanup or eviction. The cache size is not limited — delete files manually to free disk space.
+`DirectoryCache` stores one jar per module under a directory of your choice. Writes are atomic, so several processes can share a cache. Nothing is ever evicted: delete files to free disk space.
 
-### Using the Directory Cache
-
-We assume you already use the runtime compiler. If not, see the [Runtime Compiler](../execution/runtime-compiler) guide first.
-
-### Add the Maven Dependency
-
-Add the following dependency:
+Add the dependency:
 
 ```xml
 <dependency>
@@ -55,8 +34,6 @@ Add the following dependency:
 </dependency>
 ```
 
-### Code
-
 Create the cache:
 
 <!--
diff --git a/docs/docs/execution/runtime-compiler.md b/docs/docs/execution/runtime-compiler.md
index 622f9b9f7..403d7664e 100644
--- a/docs/docs/execution/runtime-compiler.md
+++ b/docs/docs/execution/runtime-compiler.md
@@ -1,29 +1,22 @@
 ---
 sidebar_position: 1
-sidebar_label: Runtime Compilation
-title: Runtime Compilation
+sidebar_label: Runtime Compiler
+title: Runtime Compiler
 ---
-## Overview
-
-:::warning[Security Consideration]
-The compiler translates Wasm to JVM bytecode without post-compilation verification. When compiling untrusted modules, prefer the interpreter for higher assurance, or run compiled code in an isolated classloader. See [Security Model](/docs/security/overview).
-:::
-
-:::info[Resource Limits]
-Compiling very large Wasm modules can consume significant memory and CPU. Consider setting JVM heap limits and compilation timeouts when processing untrusted input.
-:::
 
 The runtime compiler translates Wasm functions to JVM bytecode in memory when the instance is created, as a drop-in replacement for the interpreter.
 Compiled code runs much faster and uses less memory than interpreted code, at the cost of a small delay at instantiation.
 Use the [build-time compiler](./build-time-compiler.md) to move that work into your build.
 
-Modules that use SIMD (`v128`) instructions cannot be compiled and must run in the interpreter.
+:::warning[Security Consideration]
+The compiler generates JVM bytecode without a separate verification pass. Prefer the interpreter for untrusted modules, and bound heap and time when compiling untrusted input. See [Security Model](/docs/security/overview).
+:::
 
-## Using
+Modules that use SIMD (`v128`) instructions cannot be compiled and must run in the interpreter.
 
-### Required Maven Changes
+## Usage
 
-Add the following dependency:
+Add the dependency:
 
 ```xml
 <dependency>
@@ -32,10 +25,7 @@ Add the following dependency:
 </dependency>
 ```
 
-### Code Changes
-
-You enable the runtime compiler by configuring the instance to use `MachineFactoryCompiler::compile` as the machine factory instead 
-of the default `InterpreterMachine`.
+Then configure the instance to use `MachineFactoryCompiler::compile` as its machine factory:
 
 <!--
 ```java
@@ -59,121 +49,49 @@ var instance = Instance.builder(module).
         build();
 ```
 
-### Interpreter Fall Back
-
-The WASM to bytecode compiler translates each WASM function into JVM method.  Occasionally you will find WASM module where functions are bigger than the maximum method size allowed by the JVM. In these rare cases, we fall back to executing large functions in the interpreter.  
+The runtime compiler depends on [ASM](https://asm.ow2.io/) and uses reflection, which may need extra configuration with tools like `native-image`.
 
-Since interpreted functions have worse performance, we want to make sure you are aware this is happening so the runtime compiler will log messages to standard error like: 
-
-```text
-Warning: using interpreted mode for WASM function index: 232
-```
+## Options
 
-By default, the compiler uses `InterpreterFallback.WARN` behavior, which logs warning messages when falling back to the interpreter. If you are happy with these methods being interpreted, you can configure the compiler with `InterpreterFallback.SILENT` to silence those messages:
+`MachineFactoryCompiler.builder(module)` exposes the compiler options. All of them are optional:
 
 ```java
-import run.endive.compiler.MachineFactoryCompiler;
 import run.endive.compiler.InterpreterFallback;
-import run.endive.runtime.Instance;
-import run.endive.wasm.Parser;
-import run.endive.wasm.WasmModule;
+import run.endive.compiler.MachineFactoryCompiler;
+import run.endive.compiler.MethodPrefixer;
+import java.util.Set;
 
-var module = Parser.parse(new File("your.wasm"));
 var instance = Instance.builder(module).
         withMachineFactory(
                 MachineFactoryCompiler.builder(module)
                 .withInterpreterFallback(InterpreterFallback.SILENT)
+                .withMethodPrefixer(MethodPrefixer.fromNameSection())
                 .compile()
         ).
         build();
 ```
 
-If you want to ensure the functions are never interpreted, you can modify the above to use `InterpreterFallback.FAIL` instead. This will throw an exception if any function is too large to compile.
+### Functions too large to compile
 
-An even better way to silence the use of interpreted functions (this will speed up your compile times) is to explicitly list the function indexes that should be interpreted:
+A Wasm function that exceeds the JVM method size limit runs in the interpreter instead, and the compiler prints a warning naming its function index.
+`withInterpreterFallback(InterpreterFallback.SILENT)` drops the warning; `InterpreterFallback.FAIL` turns it into an exception.
+To skip compiling functions you already know are too large, list them with `withInterpretedFunctions(Set.of(232, 251))`; any other function that turns out too large then fails.
 
-```java
-import run.endive.compiler.MachineFactoryCompiler;
-import run.endive.compiler.InterpreterFallback;
-import run.endive.runtime.Instance;
-import run.endive.wasm.Parser;
-import run.endive.wasm.WasmModule;
-import java.io.File;
-import java.util.Set;
+### Method names
 
-var module = Parser.parse(new File("your.wasm"));
-var instance = Instance.builder(module).
-        withMachineFactory(
-                MachineFactoryCompiler.builder(module)
-                .withInterpretedFunctions(Set.of(232, 251))
-                .compile()
-        ).
-        build();
-```
+Compiled methods are named `func_0`, `func_1`, and so on.
+`withMethodPrefixer(MethodPrefixer.fromNameSection())` names them after the module's name section instead, so stack traces and profiler output show the Wasm function names.
 
-Typically, you can obtain the list of the functions by running the compiler once with `InterpreterFallback.WARN`
+### Releasing function bodies
 
-### Releasing Function Bodies
-
-Once compiled, the parsed function bodies are only needed by functions that run in the interpreter.
-`compileModule()` returns the machine factory together with a copy of the module that keeps only
-those bodies and no custom sections, so the rest can be garbage collected once the original module
-is no longer referenced:
+After compilation the parsed function bodies are only needed by the interpreter.
+To let the garbage collector reclaim them, build the instance from `compileModule()` instead of `compile()`:
 
 ```java
-import run.endive.compiler.MachineFactoryCompiler;
-import run.endive.runtime.Instance;
-import run.endive.wasm.Parser;
-import java.io.File;
-
 var compiled = MachineFactoryCompiler.builder(Parser.parse(new File("your.wasm"))).compileModule();
 var instance = Instance.builder(compiled).build();
 ```
 
-### Method Names
-
-By default, the compiler names compiled methods `func_0`, `func_1`, etc. A `MethodPrefixer` lets you
-replace the `func` prefix with something more recognisable, which improves readability of thread
-dumps, profiler output and stack traces. `MethodPrefixer.fromNameSection()` uses the function names
-from the module's name section, where present:
-
-```java
-import run.endive.compiler.MachineFactoryCompiler;
-import run.endive.compiler.MethodPrefixer;
-import run.endive.runtime.Instance;
-import run.endive.wasm.Parser;
-import run.endive.wasm.WasmModule;
-import java.io.File;
-
-var module = Parser.parse(new File("your.wasm"));
-var instance = Instance.builder(module).
-        withMachineFactory(
-                MachineFactoryCompiler.builder(module)
-                .withMethodPrefixer(MethodPrefixer.fromNameSection())
-                .compile()
-        ).
-        build();
-```
-
-A prefixer supplies only the prefix; the compiler always appends `_<funcId>` to produce the method
-name (e.g. `my_func_42`). That keeps method names unique whatever the prefixer returns, and keeps the
-WASM function index recoverable from any method name.
-
-Characters that are illegal in JVM method names (`. ; [ / < >`) are replaced with underscores. A
-prefixer that needs to preserve names exactly can avoid the substitution by encoding those
-characters itself, for example by percent-encoding them.
-
-The prefix is a hint for humans inspecting a compiled method name. Tools should not parse it, and
-should use the function index instead.
-
-### Caveats 
-
-Please note that compiling and executing Wasm modules at runtime requires:
-- an external dependency on [ASM](https://asm.ow2.io/)
-- the usage of runtime reflection
-
-This is usually fine when running on a standard JVM, but it involves some additional configuration when using tools like `native-image`.
-
 <!--
 ```java
 docs.FileOps.writeResult("docs/execution", "runtime-compiler.md.result", "empty");

From f2b7f9d3932f528e8be62e87377ee2e520e4ce3a Mon Sep 17 00:00:00 2001
From: andreatp <andrea.peruffo1982@gmail.com>
Date: Wed, 4 Nov 2026 17:23:53 +0000
Subject: [PATCH 3/6] docs: reorganize the sidebar around how pages are used

Execution modes becomes the Compilation overview, CPU limits joins
Security, Annotations joins Core Concepts next to host functions. The
SIMD page is folded into the overview and the Rust example, a copy of
the Memory page with a stale target triple, becomes a tip on that
page. Old URLs redirect; approval files follow the moved pages.
---
 docs/docs/advanced/simd.md                    | 21 -------
 docs/docs/annotations/_category_.yml          |  2 -
 .../index.md => core/annotations.md}          |  4 +-
 docs/docs/core/execution-modes.md             | 29 ---------
 docs/docs/core/host-functions.md              |  2 +-
 docs/docs/core/memory.md                      |  4 ++
 docs/docs/examples/_category_.yml             |  2 -
 docs/docs/examples/rust.md                    | 59 -------------------
 docs/docs/execution/build-time-compiler.md    |  2 +-
 docs/docs/execution/index.md                  | 27 +++++++++
 docs/docs/security/best-practices.md          | 15 +----
 .../docs/{advanced => security}/cpu-limits.md | 17 ++----
 docs/docs/security/overview.md                |  2 +-
 docs/docusaurus.config.ts                     | 18 +++---
 ... => docs-core-annotations.md.approved.txt} |  0
 .../docs-core-execution-modes.md.approved.txt |  1 -
 .../docs-examples-rust.md.approved.txt        |  1 -
 ...t => docs-execution-index.md.approved.txt} |  0
 ... docs-security-cpu-limits.md.approved.txt} |  0
 19 files changed, 49 insertions(+), 157 deletions(-)
 delete mode 100644 docs/docs/advanced/simd.md
 delete mode 100644 docs/docs/annotations/_category_.yml
 rename docs/docs/{annotations/index.md => core/annotations.md} (97%)
 delete mode 100644 docs/docs/core/execution-modes.md
 delete mode 100644 docs/docs/examples/_category_.yml
 delete mode 100644 docs/docs/examples/rust.md
 create mode 100644 docs/docs/execution/index.md
 rename docs/docs/{advanced => security}/cpu-limits.md (77%)
 rename docs/tests/approvals/{docs-advanced-cpu-limits.md.approved.txt => docs-core-annotations.md.approved.txt} (100%)
 delete mode 100644 docs/tests/approvals/docs-core-execution-modes.md.approved.txt
 delete mode 100644 docs/tests/approvals/docs-examples-rust.md.approved.txt
 rename docs/tests/approvals/{docs-advanced-simd.md.approved.txt => docs-execution-index.md.approved.txt} (100%)
 rename docs/tests/approvals/{docs-annotations-index.md.approved.txt => docs-security-cpu-limits.md.approved.txt} (100%)

diff --git a/docs/docs/advanced/simd.md b/docs/docs/advanced/simd.md
deleted file mode 100644
index d401519d9..000000000
--- a/docs/docs/advanced/simd.md
+++ /dev/null
@@ -1,21 +0,0 @@
----
-sidebar_position: 2
-sidebar_label: SIMD
-title: SIMD support
----
-
-SIMD (`v128`) instructions are supported by the interpreter on every supported JDK, with no extra dependency or configuration.
-
-The runtime and build-time compilers do not support SIMD: compiling a module that uses `v128` instructions fails, so such modules must run in the interpreter.
-
-:::warning
-SIMD execution relies on validation. Keep it enabled (the default) for modules that use `v128`.
-:::
-
-<!--
-```java
-//DEPS run.endive:docs-lib:999-SNAPSHOT
-
-docs.FileOps.writeResult("docs/advanced", "simd.md.result", "empty");
-```
--->
diff --git a/docs/docs/annotations/_category_.yml b/docs/docs/annotations/_category_.yml
deleted file mode 100644
index 3f46b5dc7..000000000
--- a/docs/docs/annotations/_category_.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-label: Annotations
-position: 35
diff --git a/docs/docs/annotations/index.md b/docs/docs/core/annotations.md
similarity index 97%
rename from docs/docs/annotations/index.md
rename to docs/docs/core/annotations.md
index 5bdb4c079..58588abfb 100644
--- a/docs/docs/annotations/index.md
+++ b/docs/docs/core/annotations.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 100
+sidebar_position: 4
 sidebar_label: Annotations
 title: Annotations
 ---
@@ -143,6 +143,6 @@ Exactly how this is done depends on the build system you are using, for instance
 
 <!--
 ```java
-docs.FileOps.writeResult("docs/annotations", "index.md.result", "empty");
+docs.FileOps.writeResult("docs/core", "annotations.md.result", "empty");
 ```
 -->
diff --git a/docs/docs/core/execution-modes.md b/docs/docs/core/execution-modes.md
deleted file mode 100644
index 958efa352..000000000
--- a/docs/docs/core/execution-modes.md
+++ /dev/null
@@ -1,29 +0,0 @@
----
-sidebar_position: 4
-sidebar_label: Execution modes
-title: Execution modes
----
-
-## Overview
-
-| Mode | Performance | Dynamic Module Loading | Requirements | Output Format | Ideal Use Case |
-|---|---|---|---|---|---|
-| **Interpreter** | 🐢 Slow | ✅ Supported | None | None - fully interpreted | Default mode; highly portable; suitable for development and environments requiring dynamic loading. |
-| **Runtime Compilation** | 🐇 Fast | ✅ Supported | Requires reflection and ASM dependency | In-memory Java Bytecode | Enhanced performance; suitable when dynamic loading is needed and the usage of reflection is fine. |
-| **Build time Compilation** | 🐇 Fast | ❌ Not Supported | Build-time tools (e.g., Maven or Gradle plugins) | Plain Java Bytecode | Optimal performance; no dynamic loading; ideal for production with static modules. |
-
-## Summary
-
-- **Interpreter**: Executes WebAssembly (Wasm) modules directly without prior compilation. It's the default mode in Endive, offering maximum portability and simplicity. However, it has slower execution speed compared to compiled modes.
-
-- **Runtime Compilation**: Compiles Wasm modules to Java bytecode at runtime for fast execution. This mode requires one additional dependency on [ASM](https://asm.ow2.io/), it uses reflection, and it loads bytecode dynamically. It fully supports loading new Wasm modules on-the-fly, but it might not be supported on some platforms (such as Android, or GraalVM's native-image). 
-
-- **Build time Compilation**: Compiles Wasm modules to Java bytecode during the build process using tools like Maven or Gradle plugins. This mode offers the best performance and eliminates the need for dynamic loading and additional dependencies, making it ideal for production environments with static modules.
-
-<!--
-```java
-//DEPS run.endive:docs-lib:999-SNAPSHOT
-
-docs.FileOps.writeResult("docs/core", "execution-modes.md.result", "empty");
-```
--->
diff --git a/docs/docs/core/host-functions.md b/docs/docs/core/host-functions.md
index 3e9d41227..bcfd664a6 100644
--- a/docs/docs/core/host-functions.md
+++ b/docs/docs/core/host-functions.md
@@ -99,5 +99,5 @@ logIt.apply();
 ```
 
 :::tip
-For an easier way to write host function and interact with a Wasm module, see [Annotations](../annotations/index.md).
+For an easier way to write host function and interact with a Wasm module, see [Annotations](annotations.md).
 :::
diff --git a/docs/docs/core/memory.md b/docs/docs/core/memory.md
index 7a163a347..097a13783 100644
--- a/docs/docs/core/memory.md
+++ b/docs/docs/core/memory.md
@@ -24,6 +24,10 @@ docs.FileOps.copyFromWasmCorpus("count_vowels.rs.wasm", "count_vowels.wasm");
 ```
 -->
 
+:::tip
+A module like this one is a Rust library built with `rustc --target=wasm32-unknown-unknown --crate-type=cdylib`. Use `--target=wasm32-wasip1` for programs that need [WASI](../wasi/index.md).
+:::
+
 Build and instantiate this module:
 
 ```java
diff --git a/docs/docs/examples/_category_.yml b/docs/docs/examples/_category_.yml
deleted file mode 100644
index e2c291542..000000000
--- a/docs/docs/examples/_category_.yml
+++ /dev/null
@@ -1,2 +0,0 @@
-label: Examples
-position: 70
diff --git a/docs/docs/examples/rust.md b/docs/docs/examples/rust.md
deleted file mode 100644
index 08ecfc296..000000000
--- a/docs/docs/examples/rust.md
+++ /dev/null
@@ -1,59 +0,0 @@
----
-sidebar_position: 1
-sidebar_label: Rust
-title: Using Rust with Endive
----
-## Compile Rust to Wasm
-
-Compiling a Rust library to Wasm is easy and can be performed using standard `rustc` options:
-
-```bash
-rustc --target=wasm32-unknown-unknown --crate-type=cdylib
-```
-
-when you need to add support for WASI preview 1 (typically when using CLIs) you can use:
-
-```bash
-rustc --target=wasm32-wasi --crate-type=bin
-```
-
-:::tip
-For production usage, make sure to produce an optimized Wasm module by using the standard compiler options `-C opt-level = 3` (speed) or `-C opt-level = "z"` (size).
-:::
-
-## Using in Endive
-
-<!--
-```java
-//DEPS run.endive:docs-lib:999-SNAPSHOT
-//DEPS run.endive:runtime:999-SNAPSHOT
-
-docs.FileOps.copyFromWasmCorpus("count_vowels.rs.wasm", "count_vowels.rs.wasm");
-
-System.setOut(new PrintStream(
-  new BufferedOutputStream(
-    new FileOutputStream("docs/examples/rust.md.result"))));
-```
--->
-
-```java
-import run.endive.wasm.Parser;
-import run.endive.runtime.Instance;
-
-var instance = Instance.builder(Parser.parse(new File("count_vowels.rs.wasm"))).build();
-
-var alloc = instance.export("alloc");
-var dealloc = instance.export("dealloc");
-var countVowels = instance.export("count_vowels");
-
-var memory = instance.memory();
-var message = "Hello, World!";
-byte[] bytes = message.getBytes();
-int len = bytes.length;
-int ptr = (int) alloc.apply(len)[0];
-
-memory.write(ptr, bytes);
-
-var result = countVowels.apply(ptr, len)[0];
-System.out.println(result);
-```
diff --git a/docs/docs/execution/build-time-compiler.md b/docs/docs/execution/build-time-compiler.md
index 27b892dd6..9a42a4f9d 100644
--- a/docs/docs/execution/build-time-compiler.md
+++ b/docs/docs/execution/build-time-compiler.md
@@ -111,7 +111,7 @@ mvn help:describe -DgroupId=run.endive -DartifactId=endive-compiler-maven-plugin
 ### Generating module exports and imports
 
 The build-time compiler can also generate typed Java wrappers for a module's exports and imports,
-eliminating the need for the [`@WasmModuleInterface` annotation](../annotations/index.md#wasmmoduleinterface) and the annotation processor setup.
+eliminating the need for the [`@WasmModuleInterface` annotation](../core/annotations.md#wasmmoduleinterface) and the annotation processor setup.
 
 Add the `moduleInterface` parameter to the plugin configuration:
 
diff --git a/docs/docs/execution/index.md b/docs/docs/execution/index.md
new file mode 100644
index 000000000..9d051fbea
--- /dev/null
+++ b/docs/docs/execution/index.md
@@ -0,0 +1,27 @@
+---
+sidebar_position: 0
+sidebar_label: Overview
+title: Compilation
+---
+
+Endive can run a Wasm module in three ways: interpreted, compiled to JVM bytecode when the instance is created, or compiled to JVM bytecode at build time.
+
+| Mode | Performance | Dynamic module loading | Requirements | Use when |
+|---|---|---|---|---|
+| **Interpreter** | 🐢 Slow | ✅ | None | The default. Maximum portability, and the only mode that runs SIMD (`v128`) modules. |
+| **[Runtime compiler](runtime-compiler.md)** | 🐇 Fast | ✅ | ASM dependency and reflection | Modules are loaded dynamically and reflection is acceptable. |
+| **[Build-time compiler](build-time-compiler.md)** | 🐇 Fast | ❌ | Maven or Gradle plugin | Modules are known at build time. Best startup, no extra runtime dependency, works with `native-image`. |
+
+The interpreter needs nothing beyond `run.endive:runtime`.
+Both compilers translate each Wasm function to a JVM method and can leave functions too large to compile to the interpreter.
+Neither supports SIMD yet, and SIMD execution relies on validation, so keep it enabled for modules that use `v128`.
+
+[Redline](../experimental/redline.md) is an experimental fourth option that compiles the module to native code at build time.
+
+<!--
+```java
+//DEPS run.endive:docs-lib:999-SNAPSHOT
+
+docs.FileOps.writeResult("docs/execution", "index.md.result", "empty");
+```
+-->
diff --git a/docs/docs/security/best-practices.md b/docs/docs/security/best-practices.md
index cb2340988..d80ceb2fe 100644
--- a/docs/docs/security/best-practices.md
+++ b/docs/docs/security/best-practices.md
@@ -61,20 +61,7 @@ var options = WasiOptions.builder()
 
 Wasm modules can consume unbounded CPU and memory. Always set limits when running untrusted code.
 
-**CPU timeout via thread interruption:**
-
-```java title="Example"
-var executor = Executors.newSingleThreadExecutor();
-var future = executor.submit(() -> instance.export("run").apply());
-
-try {
-    var result = future.get(5, TimeUnit.SECONDS);
-} catch (TimeoutException e) {
-    future.cancel(true); // interrupts the Wasm execution
-}
-```
-
-See [CPU Limits](/docs/advanced/cpu-limits) for more patterns.
+Run untrusted code under a timeout and interrupt it when the deadline passes; see [CPU Limits](/docs/security/cpu-limits) for the patterns.
 
 ## Compiler Security
 
diff --git a/docs/docs/advanced/cpu-limits.md b/docs/docs/security/cpu-limits.md
similarity index 77%
rename from docs/docs/advanced/cpu-limits.md
rename to docs/docs/security/cpu-limits.md
index 04e60c384..38eac5dad 100644
--- a/docs/docs/advanced/cpu-limits.md
+++ b/docs/docs/security/cpu-limits.md
@@ -1,17 +1,10 @@
 ---
-sidebar_position: 1
-sidebar_label: CPU
-title: CPU
+sidebar_position: 3
+sidebar_label: CPU Limits
+title: CPU Limits
 ---
-# Limiting CPU usage
 
-:::warning[Security Consideration]
-Wasm modules can contain infinite loops. When running untrusted code, always set execution timeouts via thread interruption or an ExecutorService with a deadline. Without timeouts, a malicious module can consume 100% CPU indefinitely.
-:::
-
-Often, when running untrusted user code in our infrastructure, we want to have strong guarantees around the termination of the program.
-
-To achieve this result there are, currently, two mechanisms in Endive:
+Wasm modules can loop forever, so untrusted code needs a timeout. Endive offers two mechanisms to bound execution.
 
 ## Interrupts
 
@@ -86,6 +79,6 @@ var instance =
 
 <!--
 ```java
-docs.FileOps.writeResult("docs/advanced", "cpu-limits.md.result", "empty");
+docs.FileOps.writeResult("docs/security", "cpu-limits.md.result", "empty");
 ```
 -->
diff --git a/docs/docs/security/overview.md b/docs/docs/security/overview.md
index ed35bb4c3..fe2365a9b 100644
--- a/docs/docs/security/overview.md
+++ b/docs/docs/security/overview.md
@@ -44,7 +44,7 @@ The critical trust boundary is between **Wasm guest code** and **host functions*
 
 ## What the Sandbox Does NOT Guarantee
 
-- **CPU limits**: Wasm modules can execute infinite loops. The host must enforce timeouts (see [CPU Limits](/docs/advanced/cpu-limits)).
+- **CPU limits**: Wasm modules can execute infinite loops. The host must enforce timeouts (see [CPU Limits](/docs/security/cpu-limits)).
 - **Memory growth limits**: Modules can request memory growth up to the declared maximum. The host should set appropriate limits.
 - **Post-compilation verification**: The build-time and runtime compilers translate Wasm to JVM bytecode without a separate verification pass. For maximum assurance with untrusted code, prefer the interpreter.
 - **Cache integrity**: The [directory-based compiler cache](/docs/execution/compiler-cache/#the-directory-cache) does not verify bytecode integrity on load. Protect cache directories with restrictive permissions.
diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts
index 17f7cfe3f..c0871e352 100644
--- a/docs/docusaurus.config.ts
+++ b/docs/docusaurus.config.ts
@@ -39,8 +39,8 @@ const config: Config = {
       {
         redirects: [
           {
-            to: '/docs/annotations',
-            from: ['/docs/experimental/host-modules', '/docs/usage/annotations'],
+            to: '/docs/core/annotations',
+            from: ['/docs/experimental/host-modules', '/docs/usage/annotations', '/docs/annotations'],
           },
           {
             to: '/docs/execution/runtime-compiler',
@@ -56,27 +56,23 @@ const config: Config = {
           },
           {
             to: '/docs/core/memory',
-            from: ['/docs/usage/memory'],
+            from: ['/docs/usage/memory', '/docs/examples/rust'],
           },
           {
             to: '/docs/core/linking',
             from: ['/docs/usage/linking'],
           },
           {
-            to: '/docs/core/execution-modes',
-            from: ['/docs/usage/execution_modes'],
+            to: '/docs/execution',
+            from: ['/docs/usage/execution_modes', '/docs/core/execution-modes', '/docs/usage/simd', '/docs/advanced/simd'],
           },
           {
             to: '/docs/wasi',
             from: ['/docs/usage/wasi'],
           },
           {
-            to: '/docs/advanced/cpu-limits',
-            from: ['/docs/usage/cpu'],
-          },
-          {
-            to: '/docs/advanced/simd',
-            from: ['/docs/usage/simd'],
+            to: '/docs/security/cpu-limits',
+            from: ['/docs/usage/cpu', '/docs/advanced/cpu-limits'],
           },
           {
             to: '/docs/advanced/tools',
diff --git a/docs/tests/approvals/docs-advanced-cpu-limits.md.approved.txt b/docs/tests/approvals/docs-core-annotations.md.approved.txt
similarity index 100%
rename from docs/tests/approvals/docs-advanced-cpu-limits.md.approved.txt
rename to docs/tests/approvals/docs-core-annotations.md.approved.txt
diff --git a/docs/tests/approvals/docs-core-execution-modes.md.approved.txt b/docs/tests/approvals/docs-core-execution-modes.md.approved.txt
deleted file mode 100644
index c6cac6926..000000000
--- a/docs/tests/approvals/docs-core-execution-modes.md.approved.txt
+++ /dev/null
@@ -1 +0,0 @@
-empty
diff --git a/docs/tests/approvals/docs-examples-rust.md.approved.txt b/docs/tests/approvals/docs-examples-rust.md.approved.txt
deleted file mode 100644
index 00750edc0..000000000
--- a/docs/tests/approvals/docs-examples-rust.md.approved.txt
+++ /dev/null
@@ -1 +0,0 @@
-3
diff --git a/docs/tests/approvals/docs-advanced-simd.md.approved.txt b/docs/tests/approvals/docs-execution-index.md.approved.txt
similarity index 100%
rename from docs/tests/approvals/docs-advanced-simd.md.approved.txt
rename to docs/tests/approvals/docs-execution-index.md.approved.txt
diff --git a/docs/tests/approvals/docs-annotations-index.md.approved.txt b/docs/tests/approvals/docs-security-cpu-limits.md.approved.txt
similarity index 100%
rename from docs/tests/approvals/docs-annotations-index.md.approved.txt
rename to docs/tests/approvals/docs-security-cpu-limits.md.approved.txt

From 8a415cbc738eca1533837a55a6745ef237b39b2c Mon Sep 17 00:00:00 2001
From: andreatp <andrea.peruffo1982@gmail.com>
Date: Wed, 4 Nov 2026 17:28:49 +0000
Subject: [PATCH 4/6] docs: consistency pass

One heading convention (frontmatter title, body sections from h2),
one version placeholder, one set of names for the execution modes,
shorter security admonitions that defer to the Security section, and
a descriptive first sentence on every page for llms.txt. The Quick
Start keeps one dependency snippet and defers to Installation. The
Annotations type table now lists the string, Instance and Memory
parameters the processor accepts.
---
 docs/blog/2025-02-20-chicory-1.1.0.md      |  2 +-
 docs/docs/advanced/logging.md              |  2 -
 docs/docs/advanced/memory-customization.md | 11 ++---
 docs/docs/advanced/tools.md                | 17 ++++----
 docs/docs/ai-friendly-docs.md              |  2 -
 docs/docs/core/annotations.md              | 25 ++++++------
 docs/docs/core/linking.md                  | 11 +----
 docs/docs/core/memory.md                   |  7 +---
 docs/docs/execution/compiler-cache.md      |  4 +-
 docs/docs/experimental/cli.md              |  6 +--
 docs/docs/experimental/redline.md          | 18 ++++-----
 docs/docs/experimental/why.md              |  2 -
 docs/docs/getting-started/installation.md  |  2 -
 docs/docs/index.md                         | 47 ++++++++--------------
 docs/docs/migration/from-chicory.md        |  2 -
 docs/docs/security/best-practices.md       |  2 -
 docs/docs/security/overview.md             |  2 -
 docs/docs/wasi/index.md                    | 26 ++++++------
 18 files changed, 70 insertions(+), 118 deletions(-)

diff --git a/docs/blog/2025-02-20-chicory-1.1.0.md b/docs/blog/2025-02-20-chicory-1.1.0.md
index b06301415..59f6026af 100644
--- a/docs/blog/2025-02-20-chicory-1.1.0.md
+++ b/docs/blog/2025-02-20-chicory-1.1.0.md
@@ -33,5 +33,5 @@ With this release, we’re introducing a **“Who Uses Chicory?”** section in
 
 Try out **Chicory 1.1.0** today, and let us know what you think!
 
-[simd]: /docs/advanced/simd  
+[simd]: /docs/execution  
 [memory]: /docs/advanced/memory-customization
diff --git a/docs/docs/advanced/logging.md b/docs/docs/advanced/logging.md
index 50f10caf1..47913743e 100644
--- a/docs/docs/advanced/logging.md
+++ b/docs/docs/advanced/logging.md
@@ -3,8 +3,6 @@ sidebar_position: 4
 sidebar_label: Logging
 title: Logging
 ---
-# Logging
-
 For maximum compatibility and to avoid external dependencies we use, by default, the JDK Platform Logging ([JEP 264](https://openjdk.org/jeps/264)).
 The Platform Logging falls back to the [`java.util.logging` API](https://docs.oracle.com/en/java/javase/21/core/java-logging-overview.html) by default.
 
diff --git a/docs/docs/advanced/memory-customization.md b/docs/docs/advanced/memory-customization.md
index 29b6c4813..06d68d6df 100644
--- a/docs/docs/advanced/memory-customization.md
+++ b/docs/docs/advanced/memory-customization.md
@@ -1,7 +1,7 @@
 ---
 sidebar_position: 5
-sidebar_label: Memory
-title: Advanced Wasm Memory Customization
+sidebar_label: Memory Customization
+title: Memory Customization
 ---
 <!--
 ```java
@@ -19,11 +19,8 @@ var module = Parser.parse(new File("count_vowels.rs.wasm"));
 ```
 -->
 
-Different Wasm workloads will be using the memory in very different ways.
-
-Make sure you don't do changes without proper benchmarking and analysis.
-
-It's possible to provide a custom implementation of the entire Memory used by the Wasm module:
+You can replace the `Memory` implementation backing a module through `withMemoryFactory`.
+Workloads use memory in very different ways, so benchmark before changing it:
 
 ```java
 var instance = Instance.builder(module).withMemoryFactory(limits -> {
diff --git a/docs/docs/advanced/tools.md b/docs/docs/advanced/tools.md
index 662f50fc5..351c26ccb 100644
--- a/docs/docs/advanced/tools.md
+++ b/docs/docs/advanced/tools.md
@@ -1,34 +1,31 @@
 ---
 sidebar_position: 3
-sidebar_label: WABT
-title: WABT
+sidebar_label: Tools
+title: Tools
 ---
-# Tools
+Endive publishes a few WebAssembly tools as Maven artifacts, compiled to Wasm and run with Endive itself.
 
 ## WebAssembly Binary Toolkit
 
-Since we use them in the build of the project, we publish a few [wabt](https://github.com/WebAssembly/wabt) tools compiled at build time with Endive.
-Adding support for more tools is easy and we welcome contributions in this direction.
-The relevant module can be added to the build with:
+A few [wabt](https://github.com/WebAssembly/wabt) tools, the ones Endive's own build uses:
 
 ```xml
 <dependency>
   <groupId>run.endive</groupId>
   <artifactId>wabt</artifactId>
-  <version>latest-release</version>
+  <version>${endive.version}</version>
 </dependency>
 ```
 
 ## Wasm Tools
 
-As we need it to catch up with the latest development of the Wasm spec we publish a few [wasm-tools](https://github.com/bytecodealliance/wasm-tools) compiled at build time with Endive.
-The relevant module can be added to the build with:
+A few [wasm-tools](https://github.com/bytecodealliance/wasm-tools) binaries, which track the latest Wasm proposals:
 
 ```xml
 <dependency>
   <groupId>run.endive</groupId>
   <artifactId>wasm-tools</artifactId>
-  <version>latest-release</version>
+  <version>${endive.version}</version>
 </dependency>
 ```
 
diff --git a/docs/docs/ai-friendly-docs.md b/docs/docs/ai-friendly-docs.md
index 358ebec33..4390f2426 100644
--- a/docs/docs/ai-friendly-docs.md
+++ b/docs/docs/ai-friendly-docs.md
@@ -4,8 +4,6 @@ sidebar_label: AI-Friendly Docs
 title: AI-Friendly Documentation
 ---
 
-# AI-Friendly Documentation
-
 Endive documentation is designed to be easily consumed by LLMs, AI agents, and developer tools. All machine-readable files are auto-generated at build time from the same source as the human-facing site, using the [llms.txt specification](https://llmstxt.org/).
 
 ## Available Endpoints
diff --git a/docs/docs/core/annotations.md b/docs/docs/core/annotations.md
index 58588abfb..c0a8e279e 100644
--- a/docs/docs/core/annotations.md
+++ b/docs/docs/core/annotations.md
@@ -5,9 +5,8 @@ title: Annotations
 ---
 ## Host Modules
 
-Instead of writing host functions by hand, you can write a class containing annotated methods
-and let the Endive annotation processor generate the host functions for you. This is especially
-useful when you have many host functions.
+Instead of writing host functions by hand, you can annotate the methods of a class and let the Endive annotation processor generate the host functions for you.
+This is especially useful when you have many host functions.
 
 <!--
 ```java
@@ -76,14 +75,16 @@ var imports = ImportValues.builder().addFunction(demo.toHostFunctions()).build()
 
 ### Type conversions
 
-The following conversions are supported:
+Parameters and return values are converted as follows:
 
-| Java Type         | Wasm Type  |
-|-------------------|------------|
-| `int`             | `i32`      |
-| `long`            | `i64`      |
-| `float`           | `f32`      |
-| `double`          | `f64`      |
+| Java type | Wasm type |
+|-----------|-----------|
+| `int`     | `i32`     |
+| `long`    | `i64`     |
+| `float`   | `f32`     |
+| `double`  | `f64`     |
+
+Parameters can also be a `String` annotated with `@Buffer` (passed as an `i32` pointer and an `i32` length) or `@CString` (an `i32` pointer to a NUL-terminated string), both read from the module's memory, and `Instance` or `Memory`, which receive the calling instance or its memory without a Wasm parameter.
 
 ## WasmModuleInterface
 
@@ -118,7 +119,7 @@ In order to use host modules, you need to import the relevant annotations, e.g.
 <dependency>
   <groupId>run.endive</groupId>
   <artifactId>annotations</artifactId>
-  <version>latest-release</version>
+  <version>${endive.version}</version>
 </dependency>
 ```
 
@@ -134,7 +135,7 @@ Exactly how this is done depends on the build system you are using, for instance
       <path>
         <groupId>run.endive</groupId>
         <artifactId>annotations-processor</artifactId>
-        <version>latest-release</version>
+        <version>${endive.version}</version>
       </path>
     </annotationProcessorPaths>
   </configuration>
diff --git a/docs/docs/core/linking.md b/docs/docs/core/linking.md
index 99b7a698e..0308d6c83 100644
--- a/docs/docs/core/linking.md
+++ b/docs/docs/core/linking.md
@@ -3,14 +3,9 @@ sidebar_position: 3
 sidebar_label: Linking
 title: Linking
 ---
-# Linking
+A [Store](https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#store%E2%91%A0) collects host functions, globals, memories, tables and named instances, so that modules can import from each other.
 
-In the [Host Functions section](host-functions.md) we met the `Store` for the first-time.
-
-A [Store][spec] is an intermediate-level abstraction that collects Wasm function, global, memory, and table instances
-as named entities. It simplifies creating instances, especially when there are a lot of interdependencies.
-
-In the simplest case, it allows to register single host functions, globals, memories and tables. For instance, we already saw how to register a `console.log()` host function to the `Store`:
+In the simplest case it registers single host functions, globals, memories and tables, as in the `console.log` example from [Host Functions](host-functions.md):
 
 <!--
 ```java
@@ -79,8 +74,6 @@ memories and tables with matching names.
 - A `Store` _does not_ resolve interdependencies between modules in itself: if your set of modules
 have interdependencies, you will have to instantiate and register them in the right order.
 
-[spec]: https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#store%E2%91%A0
-
 <!--
 ```java
 docs.FileOps.writeResult("docs/core", "linking.md.result", "empty");
diff --git a/docs/docs/core/memory.md b/docs/docs/core/memory.md
index 097a13783..f6ebb6f4f 100644
--- a/docs/docs/core/memory.md
+++ b/docs/docs/core/memory.md
@@ -3,11 +3,8 @@ sidebar_position: 2
 sidebar_label: Memory
 title: Memory
 ---
-# Using Memory to share data
-
-Wasm only understands basic integer and float primitives.
-Passing more complex types across the boundaries involves passing low level pointers.
-To read, write, or allocate memory in a module, Endive provides the `Memory` class.
+The `Memory` class reads and writes a module's linear memory, which is how anything beyond integers and floats crosses the boundary.
+Wasm functions only take and return numbers, so more complex values are passed as pointers into that memory.
 Let's look at an example where we have a module `count_vowels.wasm`, written in Rust, that takes a string input and counts the number of vowels
 in the string:
 
diff --git a/docs/docs/execution/compiler-cache.md b/docs/docs/execution/compiler-cache.md
index 87bd1f662..ca0aa5a72 100644
--- a/docs/docs/execution/compiler-cache.md
+++ b/docs/docs/execution/compiler-cache.md
@@ -1,7 +1,7 @@
 ---
 sidebar_position: 3
-sidebar_label: Runtime Compiler Cache
-title: Runtime Compiler Cache
+sidebar_label: Compiler Cache
+title: Compiler Cache
 ---
 
 The compiler cache stores the bytecode produced by the [runtime compiler](runtime-compiler.md), so later runs skip compilation and start faster.
diff --git a/docs/docs/experimental/cli.md b/docs/docs/experimental/cli.md
index df42749fa..757c78d73 100644
--- a/docs/docs/experimental/cli.md
+++ b/docs/docs/experimental/cli.md
@@ -3,13 +3,13 @@ sidebar_position: 5
 sidebar_label: CLI
 title: CLI
 ---
-# Install and use the CLI
+The experimental Endive CLI runs a Wasm module from the command line.
 
 :::warning[Security Consideration]
-The experimental CLI uses `inheritSystemStreams()` by default, granting the Wasm module access to stdin, stdout and stderr of the host. Do not use it with untrusted modules in its current form.
+The CLI gives the module the host's stdin, stdout and stderr. Do not run untrusted modules with it.
 :::
 
-The experimental Endive CLI is available for download on Maven at the link:
+It is available for download on Maven at the link:
 
 ```
 https://repo1.maven.org/maven2/run/endive/cli-experimental/<version>/cli-experimental-<version>.sh
diff --git a/docs/docs/experimental/redline.md b/docs/docs/experimental/redline.md
index 67ed8c110..4ad11788f 100644
--- a/docs/docs/experimental/redline.md
+++ b/docs/docs/experimental/redline.md
@@ -3,7 +3,10 @@ sidebar_position: 2
 sidebar_label: Native Compilation (Redline)
 title: Native Compilation with Redline
 ---
-## Overview
+Redline compiles your Wasm module to native machine code using [Cranelift](https://cranelift.dev/),
+instead of to JVM bytecode. Compilation happens at build time for every supported platform, and the
+right one is selected at runtime. Nothing is compiled at runtime: the runners only load the
+precompiled code, and Cranelift is not one of their dependencies.
 
 :::warning[Experimental]
 Redline is experimental, see [Why](why.md) for what that means for stability.
@@ -11,13 +14,8 @@ It also supports less of the WebAssembly specification than the other execution
 modes, so check [Feature support](#feature-support) before adopting it.
 :::
 
-Redline compiles your Wasm module to native machine code using [Cranelift](https://cranelift.dev/),
-instead of to JVM bytecode. Compilation happens at build time for every supported platform, and the
-right one is selected at runtime. Nothing is compiled at runtime: the runners only load the
-precompiled code, and Cranelift is not one of their dependencies.
-
-It is a substitute for the [Build Time Compiler](../execution/build-time-compiler.md) only, not for
-the interpreter or the [Runtime Compiler](../execution/runtime-compiler.md), and it is enabled on
+It is a substitute for the [build-time compiler](../execution/build-time-compiler.md) only, not for
+the interpreter or the [runtime compiler](../execution/runtime-compiler.md), and it is enabled on
 the same Maven plugin. The bytecode is still generated, and is used at runtime when the
 architecture or operating system is not supported.
 
@@ -150,7 +148,7 @@ may keep some for a while after their entries are overwritten.
 ## Falling back
 
 When native code cannot be used, `builder()` falls back to the bytecode produced by the
-[Build Time Compiler](../execution/build-time-compiler.md), which is always generated alongside it.
+[build-time compiler](../execution/build-time-compiler.md), which is always generated alongside it.
 This happens on platforms outside the table above, or when no runner is on the classpath. A jffi
 runner without jffi is an error, not a fallback.
 
@@ -181,7 +179,7 @@ The available triples are `x86_64-unknown-linux-gnu`, `aarch64-unknown-linux-gnu
 `x86_64-apple-darwin`, `aarch64-apple-darwin`, `x86_64-pc-windows-msvc` and
 `aarch64-pc-windows-msvc`.
 
-**Build time.** Compiling for every platform takes noticeably longer than the build time compiler
+**Build time.** Compiling for every platform takes noticeably longer than the build-time compiler
 alone. Narrowing the target list helps here too.
 
 **Imported memories, tables and globals.** Create anything you pass in through `ImportValues` from
diff --git a/docs/docs/experimental/why.md b/docs/docs/experimental/why.md
index 1bff87ed1..39bcaffac 100644
--- a/docs/docs/experimental/why.md
+++ b/docs/docs/experimental/why.md
@@ -3,8 +3,6 @@ sidebar_position: 1
 sidebar_label: Why
 title: Why
 ---
-# Why?
-
 Endive is a young project and we acknowledge that we are exploring and spearheading in many aspects the usage of Web Assembly on the JVM.
 
 Since there is (always) some degree of experimentation going on, and we want to have feedback by the community and early users, we decide to publish also `experimental` modules; everyone is welcome to try things out and report back the experience.
diff --git a/docs/docs/getting-started/installation.md b/docs/docs/getting-started/installation.md
index 21eb77452..6605edba2 100644
--- a/docs/docs/getting-started/installation.md
+++ b/docs/docs/getting-started/installation.md
@@ -3,8 +3,6 @@ sidebar_position: 1
 sidebar_label: Installation
 title: Installation
 ---
-# Installation
-
 Endive requires **Java 11** or later.
 
 Add Endive to your project using Maven or Gradle.
diff --git a/docs/docs/index.md b/docs/docs/index.md
index 33b7047eb..e4dc9d928 100644
--- a/docs/docs/index.md
+++ b/docs/docs/index.md
@@ -1,36 +1,28 @@
 ---
 sidebar_position: 1
 sidebar_label: Quick Start
-title: Quick start
+title: Quick Start
 ---
 
+This page goes from an empty project to calling a function exported by a Wasm module.
+
 :::info[Requirements]
 Endive requires **Java 11** or later.
 :::
 
-### Install the dependency
-
-[![Maven Central](https://img.shields.io/maven-central/v/run.endive/runtime)](https://central.sonatype.com/artifact/run.endive/runtime)
-
-To use the runtime, you need to add the `run.endive:runtime` dependency
-to your dependency management system.
+## Install
 
-#### Maven
+Add the runtime to your project:
 
 ```xml
 <dependency>
   <groupId>run.endive</groupId>
   <artifactId>runtime</artifactId>
-  <version>latest-release</version>
+  <version>${endive.version}</version>
 </dependency>
 ```
 
-#### Gradle
-
-```groovy
-implementation 'run.endive:runtime:latest-release'
-```
-
+See [Installation](getting-started/installation.md) for Gradle and the BOM.
 
 <!--
 ```java
@@ -39,12 +31,9 @@ implementation 'run.endive:runtime:latest-release'
 ```
 -->
 
-### Loading and Instantiating Wasm Modules
-
-First your Wasm module must be loaded from disk and then instantiated. Let's [download a test module](https://raw.githubusercontent.com/bytecodealliance/endive/main/wasm-corpus/src/main/resources/compiled/iterfact.wat.wasm) .
-This module contains some code to compute factorial:
+## Load and instantiate a module
 
-Download from the link or with curl:
+[Download a test module](https://raw.githubusercontent.com/bytecodealliance/endive/main/wasm-corpus/src/main/resources/compiled/iterfact.wat.wasm) that computes a factorial, from the link or with curl:
 
 ```bash
 curl https://raw.githubusercontent.com/bytecodealliance/endive/main/wasm-corpus/src/main/resources/compiled/iterfact.wat.wasm > factorial.wasm
@@ -56,7 +45,7 @@ docs.FileOps.copyFromWasmCorpus("iterfact.wat.wasm", "factorial.wasm");
 ```
 -->
 
-Load this module and instantiate it:
+Parse it and create an instance:
 
 ```java
 import run.endive.runtime.ExportFunction;
@@ -70,25 +59,21 @@ var module = Parser.parse(new File("./factorial.wasm"));
 Instance instance = Instance.builder(module).build();
 ```
 
+The module is inert code; the instance is a virtual machine ready to execute it.
+
 :::note[Threading]
 `Instance` and `Store` are not thread-safe. Create separate instances per thread, or synchronize access externally. Memory operations (used by the Wasm threads proposal) are thread-safe.
 :::
 
-You can think of the `module` as of inert code, and the `instance` 
-is the run-time representation of that code: a virtual machine ready to execute.
-
-### Invoking a Wasm Function
+## Call a function
 
-Wasm modules, like all code modules, can export functions to the outside
-world. This module exports a function called `"iterFact"`. 
-We can get a handle to this function using `Instance#export(String)`:
+The module exports a function called `iterFact`. Get a handle to it with `Instance#export(String)`:
 
 ```java
 ExportFunction iterFact = instance.export("iterFact");
 ```
 
-`iterFact` can be invoked with the `apply()` method. We must map any Java types to raw `long`s and do the reverse
-when we want to go back to Java.
+Call it with `apply()`. Arguments and results are raw `long`s, so map Java types yourself on both sides:
 
 ```java
 var result = iterFact.apply(5)[0];
@@ -102,5 +87,5 @@ docs.FileOps.writeResult("docs", "index.md.result", "" + result);
 -->
 
 :::note
-Functions in Wasm can return multiple values, hence the array. This function only returns one value, so we take the first value.
+Wasm functions can return multiple values, hence the array. This one returns a single value, so we take the first.
 :::
diff --git a/docs/docs/migration/from-chicory.md b/docs/docs/migration/from-chicory.md
index 6f6cedce6..b555e75f6 100644
--- a/docs/docs/migration/from-chicory.md
+++ b/docs/docs/migration/from-chicory.md
@@ -4,8 +4,6 @@ sidebar_label: From Chicory
 title: Migrating from Chicory
 ---
 
-# Migrating from Chicory to Endive
-
 Endive is a fork of [Chicory](https://github.com/dylibso/chicory) by Dylibso, Inc.
 This guide documents all breaking changes for users migrating from Chicory.
 
diff --git a/docs/docs/security/best-practices.md b/docs/docs/security/best-practices.md
index d80ceb2fe..85f55b82e 100644
--- a/docs/docs/security/best-practices.md
+++ b/docs/docs/security/best-practices.md
@@ -4,8 +4,6 @@ sidebar_label: Best Practices
 title: Security Best Practices
 ---
 
-# Security Best Practices
-
 Practical guidance for running Wasm modules securely with Endive.
 
 ## Writing Safe Host Functions
diff --git a/docs/docs/security/overview.md b/docs/docs/security/overview.md
index fe2365a9b..428d7247c 100644
--- a/docs/docs/security/overview.md
+++ b/docs/docs/security/overview.md
@@ -4,8 +4,6 @@ sidebar_label: Security Model
 title: Security Model
 ---
 
-# Security Model
-
 Endive executes WebAssembly modules inside the JVM. Understanding the security boundaries is essential when running untrusted code.
 
 ## The Wasm Sandbox
diff --git a/docs/docs/wasi/index.md b/docs/docs/wasi/index.md
index 258810a3c..f23632d17 100644
--- a/docs/docs/wasi/index.md
+++ b/docs/docs/wasi/index.md
@@ -3,12 +3,6 @@ sidebar_position: 50
 sidebar_label: WASI P1
 title: Wasi Preview 1
 ---
-# WASI Preview 1
-
-:::warning[Security Consideration]
-WASI file access does not enforce path sandboxing by default. Always use a virtual filesystem (e.g., [ZeroFs](https://github.com/roastedroot/zerofs) or [Jimfs](https://github.com/google/jimfs)) to restrict guest access to pre-opened directories. Passing the host filesystem directly exposes all files the JVM process can access. See [Security Best Practices](/docs/security/best-practices).
-:::
-
 <!--
 ```java
 //DEPS run.endive:wasi:999-SNAPSHOT
@@ -30,17 +24,22 @@ to provide system-level capabilities, such as:
 All such capabilities are virtualized; i.e., the _guest_ will not have direct
 access to the corresponding _host_ resources, but they will be mediated by the WASI layer,
 which can be configured to limit their surface.
+
+:::warning[Security Consideration]
+Map only virtual file system directories (for example [ZeroFs](https://github.com/roastedroot/zerofs) or [Jimfs](https://github.com/google/jimfs)): a host directory exposes everything the JVM process can read. See [Security Best Practices](/docs/security/best-practices).
+:::
+
 Add the dependency to your build:
 
 ```xml
 <dependency>
   <groupId>run.endive</groupId>
   <artifactId>wasi</artifactId>
-  <version>latest-release</version>
+  <version>${endive.version}</version>
 </dependency>
 ```
 
-## How to use
+## Usage
 
 As a host who is running Wasm modules, WASI is just a collection of imports that you need to provide
 to a wasi-compiled module when instantiating it. You'll also need to configure some options for how
@@ -48,7 +47,7 @@ these functions behave and what the module can and cannot do.
 
 Remember that you have full control over those functions, you can use just part of provided implementation or swap in specific implementations to better control what is being executed.
 
-### WasiPreview1 Instantiation
+### Instantiation
 
 In order to instantiate a WASI module you need an instance of `WasiPreview1`. 
 
@@ -150,7 +149,7 @@ a convenient shorthand for doing the same is:
 var wasi = WasiOptions.builder().inheritSystemStreams().build()
 ```
 
-## arguments
+## Arguments
 
 Especially when using CLIs, it's useful to provide command line arguments to the Wasm Module.
 
@@ -160,7 +159,7 @@ You can do that by using:
 var wasi = WasiOptions.builder().withArguments(List.of("executable-name", "--more", "--options")).build();
 ```
 
-## environment variables
+## Environment variables
 
 To expose environment variables to your WASI module you can list them in the options:
 
@@ -171,7 +170,7 @@ var wasi = WasiOptions.builder().
     build();
 ```
 
-## disk
+## Disk
 
 File access goes through a virtual file system, which confines the guest to the directories you map. The example uses [Google's Jimfs](https://github.com/google/jimfs):
 
@@ -196,8 +195,7 @@ try (FileSystem fs = Jimfs.newFileSystem(Configuration.unix().toBuilder().setAtt
 }
 ```
 
-## Supported Features
-
+## Supported functions
 
 If your module calls a WASI function that we don't support, or uses a feature that we don't support, we will throw a `WasmRuntimeException`.
 

From 0246c728bd0cf854941b8ad980d65237b555627c Mon Sep 17 00:00:00 2001
From: andreatp <andrea.peruffo1982@gmail.com>
Date: Wed, 4 Nov 2026 18:16:41 +0000
Subject: [PATCH 5/6] docs: feature matrix, GC types page, memory limits

Add a per-mode feature support table to the Compilation overview, a
GC Types page showing applyWithRefs, WasmStruct and reference-taking
host functions with a runnable corpus module, and a memory limits
section on the Memory page linked from the security pages.
---
 docs/docs/core/gc-types.md                    | 90 +++++++++++++++++++
 docs/docs/core/memory.md                      | 16 ++++
 docs/docs/execution/index.md                  | 18 ++++
 docs/docs/security/best-practices.md          |  2 +
 docs/docs/security/overview.md                |  2 +-
 .../docs-core-gc-types.md.approved.txt        |  1 +
 6 files changed, 128 insertions(+), 1 deletion(-)
 create mode 100644 docs/docs/core/gc-types.md
 create mode 100644 docs/tests/approvals/docs-core-gc-types.md.approved.txt

diff --git a/docs/docs/core/gc-types.md b/docs/docs/core/gc-types.md
new file mode 100644
index 000000000..ad0fa08cf
--- /dev/null
+++ b/docs/docs/core/gc-types.md
@@ -0,0 +1,90 @@
+---
+sidebar_position: 5
+sidebar_label: GC Types
+title: GC Types
+---
+
+Modules built with the WebAssembly garbage collection proposal exchange structs, arrays and `externref` values with the host as ordinary Java objects, which the JVM garbage collector manages like any other.
+
+Download a module that defines a `point` struct:
+
+```bash
+curl https://raw.githubusercontent.com/bytecodealliance/endive/main/wasm-corpus/src/main/resources/compiled/gc.wat.wasm > gc.wasm
+```
+
+<!--
+```java
+//DEPS run.endive:docs-lib:999-SNAPSHOT
+//DEPS run.endive:runtime:999-SNAPSHOT
+
+docs.FileOps.copyFromWasmCorpus("gc.wat.wasm", "gc.wasm");
+```
+-->
+
+## Calling exports that use references
+
+Use `applyWithRefs` instead of `apply` for an export whose signature contains a reference type; `apply` throws on those.
+The first array has one slot per parameter and carries the numeric arguments; the second carries the reference arguments, in order:
+
+```java
+import run.endive.runtime.Instance;
+import run.endive.runtime.WasmStruct;
+import run.endive.wasm.Parser;
+import java.io.File;
+
+var instance = Instance.builder(Parser.parse(new File("./gc.wasm"))).build();
+
+// (param i32 i32) (result (ref $point))
+var point = (WasmStruct) instance.export("new_point").applyWithRefs(new long[] {3, 4}, null).refResult(0);
+
+// (param (ref null $point)) (result i32)
+var sum = instance.export("sum").applyWithRefs(new long[] {0}, new Object[] {point}).longResult(0);
+assert(7L == sum);
+```
+
+The returned `CallResult` exposes numeric results through `longResult(i)` and reference results through `refResult(i)`.
+
+## Reading and building structs and arrays
+
+`WasmStruct` exposes its fields by index: `field(i)` for numeric fields and `fieldRef(i)` for reference fields.
+`WasmArray` does the same with `get(i)` and `getRef(i)`.
+To create one on the host, use the builder and add the fields in declaration order:
+
+```java
+assert(3L == point.field(0));
+
+var origin = WasmStruct.builder().
+        typeIdx(point.typeIdx()).
+        addField(0).
+        addField(0).
+        build();
+assert(0L == instance.export("sum").applyWithRefs(new long[] {0}, new Object[] {origin}).longResult(0));
+```
+
+<!--
+```java
+docs.FileOps.writeResult("docs/core", "gc-types.md.result", "" + sum);
+```
+-->
+
+## Host functions receiving references
+
+A host function whose signature contains reference types implements `applyWithRefs` on `WasmFunctionHandle`, and is then wrapped in a `HostFunction` like any other:
+
+```java
+import run.endive.runtime.CallResult;
+import run.endive.runtime.WasmFunctionHandle;
+
+var handle = new WasmFunctionHandle() {
+    @Override
+    public long[] apply(Instance instance, long... args) {
+        throw new UnsupportedOperationException("called with references, use applyWithRefs");
+    }
+
+    @Override
+    public CallResult applyWithRefs(Instance instance, long[] args, Object[] refArgs) {
+        var p = (WasmStruct) refArgs[0];
+        return CallResult.of(new long[] {p.field(0) + p.field(1)}, null);
+    }
+};
+```
diff --git a/docs/docs/core/memory.md b/docs/docs/core/memory.md
index f6ebb6f4f..60baeccf2 100644
--- a/docs/docs/core/memory.md
+++ b/docs/docs/core/memory.md
@@ -69,6 +69,22 @@ dealloc.apply(ptr, len);
 assert(3L == result); // 3 vowels in Hello, World!
 ```
 
+## Limiting memory growth
+
+A module declares the initial and maximum size of its memory in 64 KiB pages, and the maximum defaults to 4 GiB when it declares none.
+To cap how far an untrusted module can grow, override the limits of its memory when building the instance:
+
+```java
+import run.endive.wasm.types.MemoryLimits;
+
+// keep the declared 17 initial pages, allow growth up to 32 pages (2 MiB)
+var limited = Instance.builder(Parser.parse(new File("./count_vowels.wasm"))).
+        withMemoryLimits(new MemoryLimits(17, 32)).
+        build();
+```
+
+Past the maximum, `memory.grow` fails inside the module. The override applies to the memory the module defines; an imported memory keeps the limits it was created with.
+
 <!--
 ```java
 docs.FileOps.writeResult("docs/core", "memory.md.result", "" + result);
diff --git a/docs/docs/execution/index.md b/docs/docs/execution/index.md
index 9d051fbea..a8c655f78 100644
--- a/docs/docs/execution/index.md
+++ b/docs/docs/execution/index.md
@@ -18,6 +18,24 @@ Neither supports SIMD yet, and SIMD execution relies on validation, so keep it e
 
 [Redline](../experimental/redline.md) is an experimental fourth option that compiles the module to native code at build time.
 
+## Feature support
+
+The compilers pass the same specification test suite as the interpreter, with SIMD as the one exception.
+
+| Proposal | Interpreter | Runtime and build-time compilers | Redline |
+|---|---|---|---|
+| Core specification | ✅ | ✅ | ✅ |
+| Bulk memory and reference types | ✅ | ✅ | ✅ |
+| Tail calls | ✅ | ✅ | ✅ |
+| Threads and atomics | ✅ | ✅ | ✅ |
+| Typed function references | ✅ | ✅ | ❌ |
+| Garbage collection | ✅ | ✅ | ❌ |
+| Exception handling | ✅ | ✅ | ❌ |
+| Multi-memory | ✅ | ✅ | ❌ |
+| SIMD | ✅ | ❌ | ❌ |
+
+GC types cross the host boundary as Java objects, see [GC Types](../core/gc-types.md). [WASI Preview 1](../wasi/index.md) is a separate module and works with every mode.
+
 <!--
 ```java
 //DEPS run.endive:docs-lib:999-SNAPSHOT
diff --git a/docs/docs/security/best-practices.md b/docs/docs/security/best-practices.md
index 85f55b82e..9d26aec09 100644
--- a/docs/docs/security/best-practices.md
+++ b/docs/docs/security/best-practices.md
@@ -59,6 +59,8 @@ var options = WasiOptions.builder()
 
 Wasm modules can consume unbounded CPU and memory. Always set limits when running untrusted code.
 
+Cap memory growth with `withMemoryLimits`; see [Limiting memory growth](/docs/core/memory#limiting-memory-growth).
+
 Run untrusted code under a timeout and interrupt it when the deadline passes; see [CPU Limits](/docs/security/cpu-limits) for the patterns.
 
 ## Compiler Security
diff --git a/docs/docs/security/overview.md b/docs/docs/security/overview.md
index 428d7247c..8cd72e2c9 100644
--- a/docs/docs/security/overview.md
+++ b/docs/docs/security/overview.md
@@ -43,7 +43,7 @@ The critical trust boundary is between **Wasm guest code** and **host functions*
 ## What the Sandbox Does NOT Guarantee
 
 - **CPU limits**: Wasm modules can execute infinite loops. The host must enforce timeouts (see [CPU Limits](/docs/security/cpu-limits)).
-- **Memory growth limits**: Modules can request memory growth up to the declared maximum. The host should set appropriate limits.
+- **Memory growth limits**: Modules can request memory growth up to the declared maximum. The host should set appropriate limits (see [Limiting memory growth](/docs/core/memory#limiting-memory-growth)).
 - **Post-compilation verification**: The build-time and runtime compilers translate Wasm to JVM bytecode without a separate verification pass. For maximum assurance with untrusted code, prefer the interpreter.
 - **Cache integrity**: The [directory-based compiler cache](/docs/execution/compiler-cache/#the-directory-cache) does not verify bytecode integrity on load. Protect cache directories with restrictive permissions.
 
diff --git a/docs/tests/approvals/docs-core-gc-types.md.approved.txt b/docs/tests/approvals/docs-core-gc-types.md.approved.txt
new file mode 100644
index 000000000..7f8f011eb
--- /dev/null
+++ b/docs/tests/approvals/docs-core-gc-types.md.approved.txt
@@ -0,0 +1 @@
+7

From c2aa2e5ceca192e41884da843f4ef68467524e02 Mon Sep 17 00:00:00 2001
From: andreatp <andrea.peruffo1982@gmail.com>
Date: Thu, 5 Nov 2026 18:04:44 +0000
Subject: [PATCH 6/6] docs: writing rules in CONTRIBUTING, memory
 implementations, review fixes

Move the docs writing rules to CONTRIBUTING.md and state the trade-offs
of ByteBufferMemory and ByteArrayMemory as discussed in #224. Clarify
what memory limits cover (first memory only, no WasmGC allocations),
fix the host function sample on the best practices page, and tidy
wording and unused imports found in a self review.
---
 CONTRIBUTING.md                            | 12 ++++
 docs/README.md                             |  9 +--
 docs/docs/advanced/memory-customization.md | 31 ++++++---
 docs/docs/ai-friendly-docs.md              |  3 +-
 docs/docs/core/annotations.md              | 73 +++++++++++-----------
 docs/docs/core/host-functions.md           |  7 +--
 docs/docs/core/memory.md                   |  7 ++-
 docs/docs/execution/build-time-compiler.md |  2 +-
 docs/docs/execution/index.md               |  2 +-
 docs/docs/execution/runtime-compiler.md    |  3 +-
 docs/docs/security/best-practices.md       |  2 +-
 docs/docs/security/cpu-limits.md           |  3 +-
 docs/docs/security/overview.md             |  2 +-
 docs/docs/wasi/index.md                    |  6 +-
 14 files changed, 86 insertions(+), 76 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5d579a655..2b5c3acc8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -12,6 +12,7 @@ But first, read this page (including the small print at the end).
   + [Coding Guidelines](#coding-guidelines)
   + [Continuous Integration](#continuous-integration)
   + [Tests and documentation are not optional](#tests-and-documentation-are-not-optional)
+  + [Writing docs](#writing-docs)
 * [Reporting an issue](#reporting-an-issue)
 * [AI Tool Use Policy](#ai-tool-use-policy)
 * [Legal](#legal)
@@ -159,6 +160,17 @@ To automatically apply and approve e new version of the "Golden samples" used by
 APPROVAL_TESTS_USE_REPORTER=AutoApproveReporter
 ```
 
+### Writing docs
+
+The website lives in `docs/` (see [its README](docs/README.md) for the build). Every page under `docs/docs/` follows these rules:
+
+- Describe how to use a feature, not how it is implemented. Internals belong in Javadoc or in the pull request description.
+- No release-time or migration statements. Those go in a blog post; breaking changes relative to Chicory go in the migration guide.
+- One code sample per option. Show a builder once per page.
+- Body headings start at `##`; the frontmatter `title` is the page heading. Open every page with one plain sentence saying what it covers, which becomes its description in `llms.txt`.
+- Names: Wasm, interpreter, runtime compiler, build-time compiler. Version placeholder: `${endive.version}`.
+- Every page is executed by `npm test` in `docs/`: keep the hidden `//DEPS` and `docs.FileOps.writeResult(...)` blocks, and update `docs/tests/approvals/` when a page moves.
+
 ## Reporting an issue
 
 This project uses GitHub issues to manage the issues. Open an issue directly in GitHub.
diff --git a/docs/README.md b/docs/README.md
index 1bba3401b..35f5aff81 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -25,11 +25,4 @@ $ npm run build
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
 
-### Writing docs
-
-- Describe how to use a feature, not how it is implemented. Internals belong in Javadoc or in the pull request description.
-- No release-time or migration statements. Those go in a blog post; breaking changes relative to Chicory go in the migration guide.
-- One code sample per option. Show a builder once per page.
-- Body headings start at `##`; the frontmatter `title` is the page heading. Open every page with one plain sentence saying what it covers, which becomes its description in `llms.txt`.
-- Names: Wasm, interpreter, runtime compiler, build-time compiler. Version placeholder: `${endive.version}`.
-- Every page is executed by `npm test`: keep the hidden `//DEPS` and `docs.FileOps.writeResult(...)` blocks, and update `tests/approvals/` when a page moves.
+The rules for writing pages are in [CONTRIBUTING.md](../CONTRIBUTING.md#writing-docs).
diff --git a/docs/docs/advanced/memory-customization.md b/docs/docs/advanced/memory-customization.md
index 06d68d6df..bc6fe88a1 100644
--- a/docs/docs/advanced/memory-customization.md
+++ b/docs/docs/advanced/memory-customization.md
@@ -19,20 +19,31 @@ var module = Parser.parse(new File("count_vowels.rs.wasm"));
 ```
 -->
 
-You can replace the `Memory` implementation backing a module through `withMemoryFactory`.
-Workloads use memory in very different ways, so benchmark before changing it:
+Endive ships two implementations of linear memory, and `withMemoryFactory` selects which one backs an instance:
 
 ```java
-var instance = Instance.builder(module).withMemoryFactory(limits -> {
-        return new ByteArrayMemory(limits);
-    }).build();
+var instance = Instance.builder(module).
+        withMemoryFactory(ByteArrayMemory::new).
+        build();
 ```
 
-:::note
-Endive provides two built-in Memory implementations:
-- `ByteArrayMemory`: An optimized memory implementation, recommended for recent OpenJDK systems
-- `ByteBufferMemory`: Recommended for different Java runtimes (in particular, on Android VMs)
-:::
+## Choosing an implementation
+
+| Implementation | Plain loads and stores | Atomic instructions | Works on |
+|---|---|---|---|
+| `ByteBufferMemory` (default) | Good | Always take a lock | Every JDK and Android |
+| `ByteArrayMemory` | Fastest on every JDK | Lock-free up to JDK 21, locked from JDK 23 | Every JDK |
+
+Atomic instructions only matter for modules built with the threads proposal that share their memory between threads.
+For everything else `ByteArrayMemory` is the faster choice on a standard JVM, and `ByteBufferMemory` is the safe default where that cannot be assumed, such as Android.
+From JDK 23 the JDK no longer provides lock-free multi-byte atomics on byte arrays, so a shared memory performs the same with either implementation there.
+
+Workloads use memory in very different ways, so benchmark before changing the default.
+
+[Redline](../experimental/redline.md#native-memory) keeps linear memory off-heap with lock-free atomics; that memory comes with the Redline runners and is not selectable here.
+
+Any class implementing `Memory` can be passed to `withMemoryFactory`, for example an off-heap implementation of your own.
+The factory receives the module's declared limits, or the ones set with [`withMemoryLimits`](../core/memory.md#limiting-memory-growth).
 
 <!--
 ```java
diff --git a/docs/docs/ai-friendly-docs.md b/docs/docs/ai-friendly-docs.md
index 4390f2426..c4a820b8b 100644
--- a/docs/docs/ai-friendly-docs.md
+++ b/docs/docs/ai-friendly-docs.md
@@ -27,8 +27,7 @@ Every documentation page also has a **raw Markdown** version available by append
 Fetch `llms-full.txt` and include it in your prompt context:
 
 ```bash
-curl -s https://endive.run/llms-full.txt | wc -c
-# ~86 KB — fits easily in any modern LLM context window
+curl -s https://endive.run/llms-full.txt
 ```
 
 ### Let an AI agent discover relevant pages
diff --git a/docs/docs/core/annotations.md b/docs/docs/core/annotations.md
index c0a8e279e..9f486b3da 100644
--- a/docs/docs/core/annotations.md
+++ b/docs/docs/core/annotations.md
@@ -3,10 +3,41 @@ sidebar_position: 4
 sidebar_label: Annotations
 title: Annotations
 ---
-## Host Modules
+The annotation processor generates host functions from annotated Java methods, and typed Java bindings from a Wasm module, so you do not write the `HostFunction` boilerplate by hand.
 
-Instead of writing host functions by hand, you can annotate the methods of a class and let the Endive annotation processor generate the host functions for you.
-This is especially useful when you have many host functions.
+## Setup
+
+Add the annotations dependency:
+
+```xml
+<dependency>
+  <groupId>run.endive</groupId>
+  <artifactId>annotations</artifactId>
+  <version>${endive.version}</version>
+</dependency>
+```
+
+and register `annotations-processor` as an annotation processor of the Java compiler, with Maven:
+
+```xml
+<plugin>
+  <groupId>org.apache.maven.plugins</groupId>
+  <artifactId>maven-compiler-plugin</artifactId>
+  <configuration>
+    <annotationProcessorPaths>
+      <path>
+        <groupId>run.endive</groupId>
+        <artifactId>annotations-processor</artifactId>
+        <version>${endive.version}</version>
+      </path>
+    </annotationProcessorPaths>
+  </configuration>
+</plugin>
+```
+
+## Host modules
+
+Annotate the methods of a class and the processor generates one host function per method:
 
 <!--
 ```java
@@ -18,9 +49,8 @@ This is especially useful when you have many host functions.
 ```java
 @HostModule("demo")
 public final class Demo {
-    
-    public Demo() {}
-    
+    private final Random random = new Random();
+
     @WasmExport
     public long add(int a, int b) {
         return a + b;
@@ -111,37 +141,6 @@ This annotation generates several things, depending on the provided module:
 
 You can find examples of how to use the generated code in the [`annotations/it` folder of the repository](https://github.com/bytecodealliance/endive/tree/main/annotations/it).
 
-## Enabling the Annotation Processor
-
-In order to use host modules, you need to import the relevant annotations, e.g. in Maven:
-
-```xml
-<dependency>
-  <groupId>run.endive</groupId>
-  <artifactId>annotations</artifactId>
-  <version>${endive.version}</version>
-</dependency>
-```
-
-and configure the Java compiler to include the Endive `annotations-processor` as an annotation processor.
-Exactly how this is done depends on the build system you are using, for instance, with Maven:
-
-```xml
-<plugin>
-  <groupId>org.apache.maven.plugins</groupId>
-  <artifactId>maven-compiler-plugin</artifactId>
-  <configuration>
-    <annotationProcessorPaths>
-      <path>
-        <groupId>run.endive</groupId>
-        <artifactId>annotations-processor</artifactId>
-        <version>${endive.version}</version>
-      </path>
-    </annotationProcessorPaths>
-  </configuration>
-</plugin>
-```
-
 <!--
 ```java
 docs.FileOps.writeResult("docs/core", "annotations.md.result", "empty");
diff --git a/docs/docs/core/host-functions.md b/docs/docs/core/host-functions.md
index bcfd664a6..86b469b1b 100644
--- a/docs/docs/core/host-functions.md
+++ b/docs/docs/core/host-functions.md
@@ -15,9 +15,6 @@ Without imports a module is pure compute: it cannot perform I/O or interact with
 
 ## Writing a host function
 
-A host function is called from Wasm but runs in the JVM, so it can do anything your Java code can.
-That is also what makes it a security boundary when the module is untrusted.
-
 Download the following module, which imports a `console.log` function:
 
 ```bash
@@ -33,9 +30,7 @@ docs.FileOps.copyFromWasmCorpus("host-function.wat.wasm", "logger.wasm");
 ```
 -->
 
-This module expects us to fulfil an import with the name `console.log`. 
-As the name implies, this function allows a caller to log a message to standard output.
-We could write it as the host function:
+The module expects an import named `console.log` that prints a message, written as a host function like this:
 
 <!--
 ```java
diff --git a/docs/docs/core/memory.md b/docs/docs/core/memory.md
index 60baeccf2..799cc681e 100644
--- a/docs/docs/core/memory.md
+++ b/docs/docs/core/memory.md
@@ -3,7 +3,7 @@ sidebar_position: 2
 sidebar_label: Memory
 title: Memory
 ---
-The `Memory` class reads and writes a module's linear memory, which is how anything beyond integers and floats crosses the boundary.
+`Memory` reads and writes a module's linear memory, which is how anything beyond integers and floats crosses the boundary.
 Wasm functions only take and return numbers, so more complex values are passed as pointers into that memory.
 Let's look at an example where we have a module `count_vowels.wasm`, written in Rust, that takes a string input and counts the number of vowels
 in the string:
@@ -83,7 +83,10 @@ var limited = Instance.builder(Parser.parse(new File("./count_vowels.wasm"))).
         build();
 ```
 
-Past the maximum, `memory.grow` fails inside the module. The override applies to the memory the module defines; an imported memory keeps the limits it was created with.
+Past the maximum, `memory.grow` fails inside the module and the instance keeps running.
+The override applies to the first memory the module defines; an imported memory keeps the limits it was created with.
+Memory limits bound linear memory only: structs and arrays allocated by a [GC](gc-types.md) module live on the JVM heap and are bounded only by its size.
+To change which implementation backs the memory, see [Memory Customization](../advanced/memory-customization.md).
 
 <!--
 ```java
diff --git a/docs/docs/execution/build-time-compiler.md b/docs/docs/execution/build-time-compiler.md
index 9a42a4f9d..ff4c3d355 100644
--- a/docs/docs/execution/build-time-compiler.md
+++ b/docs/docs/execution/build-time-compiler.md
@@ -14,7 +14,7 @@ Compared to the [runtime compiler](runtime-compiler.md):
 
 - nothing is compiled at instantiation
 - no reflection and no ASM at runtime, so it works with `native-image`
-- the module ships as a self-contained jar
+- the module ships as a self-contained jar that needs only `run.endive:runtime` at runtime
 
 Modules that use SIMD (`v128`) instructions cannot be compiled and must run in the interpreter.
 
diff --git a/docs/docs/execution/index.md b/docs/docs/execution/index.md
index a8c655f78..87e44127f 100644
--- a/docs/docs/execution/index.md
+++ b/docs/docs/execution/index.md
@@ -14,7 +14,7 @@ Endive can run a Wasm module in three ways: interpreted, compiled to JVM bytecod
 
 The interpreter needs nothing beyond `run.endive:runtime`.
 Both compilers translate each Wasm function to a JVM method and can leave functions too large to compile to the interpreter.
-Neither supports SIMD yet, and SIMD execution relies on validation, so keep it enabled for modules that use `v128`.
+Neither supports SIMD. The interpreter's SIMD support relies on validation, so do not disable it for modules that use `v128`.
 
 [Redline](../experimental/redline.md) is an experimental fourth option that compiles the module to native code at build time.
 
diff --git a/docs/docs/execution/runtime-compiler.md b/docs/docs/execution/runtime-compiler.md
index 403d7664e..3b34bdb05 100644
--- a/docs/docs/execution/runtime-compiler.md
+++ b/docs/docs/execution/runtime-compiler.md
@@ -41,7 +41,6 @@ docs.FileOps.copyFromWasmCorpus("count_vowels.rs.wasm", "your.wasm");
 ```java
 import run.endive.compiler.MachineFactoryCompiler;
 import run.endive.wasm.Parser;
-import run.endive.wasm.WasmModule;
 
 var module = Parser.parse(new File("your.wasm"));
 var instance = Instance.builder(module).
@@ -85,7 +84,7 @@ Compiled methods are named `func_0`, `func_1`, and so on.
 ### Releasing function bodies
 
 After compilation the parsed function bodies are only needed by the interpreter.
-To let the garbage collector reclaim them, build the instance from `compileModule()` instead of `compile()`:
+To let the garbage collector reclaim them and keep the instance's footprint small, build the instance from `compileModule()` instead of `compile()`:
 
 ```java
 var compiled = MachineFactoryCompiler.builder(Parser.parse(new File("your.wasm"))).compileModule();
diff --git a/docs/docs/security/best-practices.md b/docs/docs/security/best-practices.md
index 9d26aec09..9f0ca413b 100644
--- a/docs/docs/security/best-practices.md
+++ b/docs/docs/security/best-practices.md
@@ -13,7 +13,7 @@ Host functions are the primary attack surface — they cross the sandbox boundar
 **Always validate arguments from Wasm:**
 
 ```java title="Example"
-HostFunction readMemory = (Instance instance, long... args) -> {
+WasmFunctionHandle readMemory = (Instance instance, long... args) -> {
     int offset = (int) args[0];
     int length = (int) args[1];
 
diff --git a/docs/docs/security/cpu-limits.md b/docs/docs/security/cpu-limits.md
index 38eac5dad..fdc030204 100644
--- a/docs/docs/security/cpu-limits.md
+++ b/docs/docs/security/cpu-limits.md
@@ -8,7 +8,7 @@ Wasm modules can loop forever, so untrusted code needs a timeout. Endive offers
 
 ## Interrupts
 
-Wasm modules executed using Endive honour the carrier thread interruption mechanism, thus you can leverage it to implement absolute timeouts:
+Endive checks the interrupt flag of the thread running the module, so interrupting that thread stops the execution with a `WasmInterruptedException`:
 
 ```bash
 curl https://raw.githubusercontent.com/bytecodealliance/endive/main/wasm-corpus/src/main/resources/compiled/infinite-loop.c.wasm > infinite-loop.wasm
@@ -54,6 +54,7 @@ Or using an `ExecutorService`:
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
 import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
 
 ExecutorService service = Executors.newSingleThreadExecutor();
 var future = service.submit(() -> function.apply());
diff --git a/docs/docs/security/overview.md b/docs/docs/security/overview.md
index 8cd72e2c9..eb984a99c 100644
--- a/docs/docs/security/overview.md
+++ b/docs/docs/security/overview.md
@@ -43,7 +43,7 @@ The critical trust boundary is between **Wasm guest code** and **host functions*
 ## What the Sandbox Does NOT Guarantee
 
 - **CPU limits**: Wasm modules can execute infinite loops. The host must enforce timeouts (see [CPU Limits](/docs/security/cpu-limits)).
-- **Memory growth limits**: Modules can request memory growth up to the declared maximum. The host should set appropriate limits (see [Limiting memory growth](/docs/core/memory#limiting-memory-growth)).
+- **Memory growth limits**: Modules can request memory growth up to the declared maximum. The host should set appropriate limits (see [Limiting memory growth](/docs/core/memory#limiting-memory-growth)). Those limits cover linear memory only: WasmGC structs and arrays are allocated on the JVM heap.
 - **Post-compilation verification**: The build-time and runtime compilers translate Wasm to JVM bytecode without a separate verification pass. For maximum assurance with untrusted code, prefer the interpreter.
 - **Cache integrity**: The [directory-based compiler cache](/docs/execution/compiler-cache/#the-directory-cache) does not verify bytecode integrity on load. Protect cache directories with restrictive permissions.
 
diff --git a/docs/docs/wasi/index.md b/docs/docs/wasi/index.md
index f23632d17..979b0b5af 100644
--- a/docs/docs/wasi/index.md
+++ b/docs/docs/wasi/index.md
@@ -1,7 +1,7 @@
 ---
 sidebar_position: 50
 sidebar_label: WASI P1
-title: Wasi Preview 1
+title: WASI Preview 1
 ---
 <!--
 ```java
@@ -64,7 +64,6 @@ docs.FileOps.copyFromWasmCorpus("hello-wasi.wat.wasm", "hello-wasi.wasm");
 -->
 
 ```java
-import run.endive.log.SystemLogger;
 import run.endive.wasi.WasiOptions;
 import run.endive.wasi.WasiPreview1;
 import run.endive.wasm.Parser;
@@ -72,7 +71,6 @@ import run.endive.runtime.Store;
 
 import java.io.File;
 
-var logger = new SystemLogger();
 // let's just use the default options for now
 var options = WasiOptions.builder().build();
 // create our instance of wasip1
@@ -121,7 +119,7 @@ var wasi = WasiPreview1.builder().withOptions(wasiOpts).build();
 // greet-wasi is a rust program that greets the string passed in stdin
 var store = new Store().addFunction(wasi.toHostFunctions());
 // instantiating will execute the module if it's a WASI command-pattern module
-store.instantiate("hello-wasi", Parser.parse(new File("greet-wasi.wasm")));
+store.instantiate("greet-wasi", Parser.parse(new File("greet-wasi.wasm")));
 
 
 // check that we output the greeting