diff --git a/Documentation~/09-troubleshooting.md b/Documentation~/09-troubleshooting.md
new file mode 100644
index 0000000..e4019dc
--- /dev/null
+++ b/Documentation~/09-troubleshooting.md
@@ -0,0 +1,453 @@
+# Troubleshooting
+
+This page lists recurring problems encountered when connecting GAMA,
+`simple.webplatform`, and Unity.
+
+Use it as a first diagnostic checklist before changing code.
+
+## Quick Checks
+
+Before investigating a specific symptom, check the following points:
+
+- GAMA is open and the target experiment is selected.
+- The experiment used by Unity is the generated `vr_xp` experiment withe the Unity Plugin, not the
+  original GAMA experiment.
+- `simple.webplatform` is running with `npm start`.
+- The Unity package is up to date.
+
+## Port Reference
+
+`simple.webplatform` exposes several ports. They do not have the same role:
+
+```text
+8000: web interface opened in the browser
+8001: monitor WebSocket used by Unity to drive preview capture
+8080: Unity player/runtime WebSocket used in Play Mode
+1000: GAMA Server behind simple.webplatform
+```
+
+Seeing the web interface on `http://localhost:8000/` does not guarantee that
+the monitor socket on `8001` or the Unity player socket on `8080` is running.
+
+## GAMA Model Was Not Converted To `vr_xp`
+
+The original GAMA experiment cannot be used directly by Unity. It must first be
+converted into a Unity-compatible `vr_xp` experiment with the SIMPLE Unity
+plugin for GAMA.
+
+If this step is skipped, Unity may connect to `simple.webplatform`, but it will
+not receive the expected Unity geometry data.
+
+## Species Were Not Exported During `vr_xp` Conversion
+
+During the `vr_xp` conversion, each species that should appear in Unity must be
+explicitly exported in the **Export species** step withe the Unity Plugin in GAMA.
+
+Do not simply click **Next** through the conversion wizard. Select each species
+on the left and click **+** under **Aspect in Unity**.
+
+If Unity logs a JSON output with `names=0`, `pointsLoc=0`, or `pointsGeom=0`,
+GAMA is probably sending an empty geometry payload.
+
+## Generate Preview Button Is Used Before GAMA Is Ready
+
+Before using **Generate Preview from GAMA**, the target experiment must be
+selected or already open in GAMA. For the tutorial workflow, start the
+`vr_xp` experiment in GAMA first, then generate the preview from Unity.
+
+If the experiment is not selected or not ready, Unity may connect to the
+middleware but fail to capture useful geometry data.
+
+Steps **in this exact order**:
+
+1. Start `simple.webplatform` with `npm start`.
+2. Open the `vr_xp` experiment in GAMA.
+3. Then, and only then, click **Generate Preview from GAMA** in Unity.
+
+## Generate Preview Says That `localhost:8001` Is Not Responding
+
+Unity shows this kind of message:
+
+```text
+The existing monitor ws://localhost:8001/ is not responding.
+Launch simple.webplatform manually, then try again.
+```
+
+This means Unity cannot reach the `simple.webplatform` monitor WebSocket. The
+browser page on `8000` may still be visible, but the backend service needed by
+Unity is not responding on `8001`.
+
+Check that `simple.webplatform` was started with:
+
+```bash
+npm start
+```
+
+Then check that the monitor and player sockets are listening.
+
+On macOS or Linux:
+
+```bash
+lsof -nP -iTCP:8001 -sTCP:LISTEN
+lsof -nP -iTCP:8080 -sTCP:LISTEN
+```
+
+On Windows:
+
+```powershell
+netstat -ano | findstr :8001
+netstat -ano | findstr :8080
+```
+
+If only port `8000` is open, the web interface is running but Unity cannot
+generate the preview. Restart `simple.webplatform` and check the terminal for
+backend errors.
+
+## Unity Connects But No Agents Appear In Play Mode
+
+If GAMA starts, Unity connects, but no simulation objects appear, check the
+following points:
+
+- the experiment is the generated `vr_xp` experiment;
+- species were exported during the `vr_xp` conversion;
+- the generated model contains `add_geometries_to_send(...)`;
+- `simple.webplatform` is listening on `8080`;
+- the Unity Console does not show repeated socket close messages;
+- the GAMA experiment is actually sending geometry updates.
+
+Useful Unity Console filters:
+
+```text
+[GAMA][RUNTIME][CONNECTION]
+[GAMA][CONNECTION]
+[GAMA][RUNTIME][FLOW]
+```
+
+If the socket is open but the JSON output is empty, the problem is usually on
+the GAMA model/export side, not on Unity rendering.
+
+## `unity_linker` Or Player Creation Fails
+
+Sometimes GAMA or `simple.webplatform` may report that the Unity linker/player
+could not be created. This can happen when the middleware keeps stale state or
+when the `vr_xp` experiment is incomplete.
+
+Fix:
+
+1. Stop the GAMA experiment.
+2. Stop `simple.webplatform`.
+3. Restart `simple.webplatform`.
+4. Re-open the experiment in GAMA.
+5. Enter Play Mode again in Unity.
+
+If the issue persists, inspect the generated GAML model:
+
+- `unity_linker_species` should point to the linker species.
+- `create_player(string id)` should ask the `unity_linker` to create the player.
+- `player_unity_properties` should not point to missing or invalid properties.
+- the species to display should be sent with `add_geometries_to_send(...)`.
+
+## GAMA Reports A Nil Value Error
+
+A GAMA error such as `nil value detected` can break the Unity flow even if the
+middleware and Unity are running.
+
+Check:
+
+- the generated `vr_xp` model compiles without errors;
+- exported Unity properties are initialized before they are used;
+- `player_unity_properties` does not contain an invalid property;
+- the experiment was regenerated after changing exported species;
+- GAMA and `simple.webplatform` were both restarted after a failed connection.
+
+If the error happens during `create_player`, regenerate the `vr_xp` experiment
+and make sure the Unity linker and exported species are present.
+
+## No Preview Is Generated
+
+Check:
+
+- `simple.webplatform` is launched first and running;
+- the experiment is then opened in GAMA (make sur to make it linkable by converting it with the Unity Plugin);
+- the GAMA experiment was converted to `vr_xp`;
+- the Unity player socket uses port `8080`;
+- the monitor socket on `8001` is reachable;
+- the GAMA model sends geometries through the Unity linker.
+
+If the preview still fails, using the develop branch of the package, open the Unity Console and search for:
+
+```text
+[GAMA][CAPTURE]
+[GAMA][PREVIEW]
+[GAMA][CONNECTION]
+```
+
+## Preview Capture Is Cancelled Or Incomplete
+
+If the preview ends with a cancelled or incomplete capture, the most common
+causes are:
+
+- the GAMA experiment was not ready when the capture started;
+- the monitor socket on `8001` disconnected;
+- the player socket on `8080` did not receive `json_output`;
+- GAMA was still starting or compiling the experiment;
+- an old middleware/player state was still active.
+
+Fix:
+
+1. Stop Play Mode in Unity.
+2. Stop or reset the GAMA experiment.
+3. Restart `simple.webplatform`.
+4. Start the `vr_xp` experiment in GAMA.
+5. Generate the preview again.
+
+If the second attempt works, the first capture most likely started before all
+services were synchronized.
+
+## Preview Settings And Game Manager Settings Seem To Do The Same Thing
+
+The preview panel and the `Game Manager` Inspector edit the same species visual
+override data.
+
+Changing values in the preview panel updates the preview scene and stores the
+settings used later by Play Mode. Editing the same species in the `Game Manager`
+Inspector changes the same kind of data.
+
+The **Validate Preview and Close Panel** button is mainly a workflow action:
+
+- it applies the current preview settings;
+- it keeps the generated preview available in Edit Mode;
+- it closes the preview panel;
+- it makes the chosen settings ready for reuse in Play Mode.
+
+If the scene already updates while editing values, this is expected. The
+validate button confirms and exits the preview workflow.
+
+## Colors Do Not Follow Attributes
+
+Unity can only use attributes that GAMA explicitly sends.
+
+Check:
+
+- the GAMA model sends the attribute in `add_geometries_to_send(...)`;
+- Unity receives non-empty attributes;
+- the species dynamic color override is enabled;
+- the selected attribute name matches the GAMA attribute key exactly;
+- discrete rules match the received values.
+
+For example, to expose a `food` attribute on `vegetation_cell`:
+
+```gaml
+list<float> grass_food <- vegetation_cell collect each.food;
+map<string, list<float>> grass_atts <- ["food":: grass_food];
+
+do add_geometries_to_send(vegetation_cell, up_vegetation_cell, grass_atts);
+```
+
+If `food` is not sent by GAMA, it will not be available in Unity dynamic color
+settings.
+
+## Discrete Dynamic Colors Cannot Be Tested On The Tutorial Model
+
+Discrete dynamic colors require an attribute with distinct values, for example a
+state, status, type, or category.
+
+If the current model only exposes continuous numeric values such as `food`, use
+the continuous dynamic color mode instead.
+
+To test discrete colors, first add or expose a categorical GAMA attribute, then
+send it through `add_geometries_to_send(...)` and configure the discrete mapping
+in Unity.
+
+## Prefab Does Not Change In Play Mode
+
+For Play Mode, the prefab must be loadable from a Unity `Resources` path.
+
+If a prefab is outside a `Resources` folder, Edit Mode preview may still use it,
+but runtime loading can fall back to the default GAMA geometry.
+
+Move runtime prefabs under a `Resources` folder or use a prefab path that can be
+resolved at runtime.
+
+## FPS Player Prefab Does Not Work
+
+The default FPS player prefab may not be configured for every project. This does
+not prevent GAMA agents from being imported, but it can make navigation or
+interaction unusable.
+
+Fix:
+
+- use the default scene setup only as a connection baseline;
+- replace the FPS player with a project-specific player prefab if needed;
+- check camera, input, colliders, and movement scripts before testing
+  interaction.
+
+## Scene Is Not Saved After Default Setup
+
+Unity does not always save the scene automatically after pressing **Default
+Setup** in the GAMA Panel.
+
+Fix:
+
+1. Press **Default Setup**.
+2. Check that the scene contains the required managers.
+3. Save the scene manually with **File > Save**.
+
+If the scene is not saved, the required objects may disappear after reopening
+the project.
+
+## Scale Looks Different Between Preview And Play Mode
+
+The scale multiplier is a visual override. It should change the size of each
+agent visual without changing the logical spread of the species.
+
+If the species looks stretched or contracted as a whole:
+
+- check that the latest Unity package version is installed;
+- regenerate the preview;
+- reset the affected species override;
+- verify that the scale is applied to agent visuals, not to the common species
+  parent object.
+
+Cell-like background species and moving agent species can have very different
+geometry shapes, so compare the result in both Edit Mode preview and Play Mode.
+
+## Geometry Mesh Needs Height Instead Of Scale
+
+When no Unity prefab is assigned, Unity uses the geometry mesh sent by GAMA. In
+that case, changing a global visual scale may not be the best control for flat
+or background geometries.
+
+Workaround:
+
+- keep the scale multiplier close to `1` for background meshes;
+- adjust the geometry height/depth in the GAMA Unity aspect when possible;
+- use prefabs when per-agent visual control is required.
+
+This is a known usability limitation: a dedicated height control for GAMA
+geometry meshes would be clearer than a generic scale control.
+
+## Play Mode Start Or Stop Is Slow
+
+Starting or stopping Play Mode may take several seconds on large scenes or when
+the connection stack is restarting.
+
+Possible causes:
+
+- WebSocket initialization or shutdown;
+- large numbers of runtime agents;
+- repeated console logging;
+- Unity recompilation or scene reload;
+- `simple.webplatform` reconnecting or purging old players.
+
+Fix:
+
+- use the `main` package branch for user testing because it has reduced default
+  logging;
+- use the `develop` branch only when detailed logs are needed;
+- keep the Unity Console collapsed when testing large simulations;
+- restart `simple.webplatform` if old sockets remain open.
+
+## Runtime Appearance Changes Cause Performance Spikes
+
+Changing colors, scale, visibility, or prefab overrides during Play Mode can
+trigger updates on many agents at once.
+
+This is expected to be more expensive on large simulations.
+
+Workaround:
+
+- configure species appearance in Edit Mode preview when possible;
+- avoid repeatedly changing overrides while thousands of agents are active;
+- use reduced logging for user testing;
+- test large visual changes on a smaller model first.
+
+## Editor Becomes Slow When Editing Game Manager Values
+
+In Edit Mode, changing `Game Manager` Inspector values can immediately update
+the preview. On large previews, this can cause editor stutter.
+
+Workaround:
+
+- prefer the GAMA Panel preview workflow for common appearance changes;
+- avoid dragging sliders continuously on very large scenes;
+- type numeric values directly instead of scrubbing controls;
+- hide or reduce the number of visible species while configuring one species.
+
+A future improvement would be a manual **Apply** button for expensive preview
+updates instead of applying every editor value change immediately.
+
+## Simulation Stops When Unity Loses Focus
+
+If Unity is not the focused application during runtime, the connection can slow
+down, pause, or be closed depending on the platform and middleware state.
+
+Workaround:
+
+- keep the Unity window focused while testing Play Mode;
+- avoid switching to another application during connection-sensitive tests;
+- if the socket closes, stop Play Mode, restart `simple.webplatform`, and run
+  the experiment again.
+
+## Agents Freeze Or Accumulate
+
+For dynamic species, Unity should receive complete enough updates to know which
+agents still exist.
+
+If agents accumulate or freeze:
+
+- check that GAMA is still running;
+- check that Unity is still connected to `simple.webplatform`;
+- verify that the runtime socket on `8080` remains open;
+- make sure the model sends regular geometry updates for dynamic species.
+
+Static or background species should not be removed just because they are absent
+from a dynamic tick.
+
+## Background Geometry Is Not Explicitly Defined During GAMA Conversion
+
+The GAMA Unity conversion wizard currently exports species and aspects, but it
+does not always make the distinction between dynamic agents and background
+geometry obvious.
+
+Workaround:
+
+- export background species separately;
+- configure their appearance in Unity preview;
+- keep background species visible and stable;
+- hide or reduce dynamic species while configuring the background.
+
+For road/building/static geometry workflows, it is useful to keep those species
+as separate exported entries so their Unity appearance can be controlled
+independently.
+
+## Background Geometry Changes Seem To Be Applied Repeatedly
+
+If background geometry or static species appear to be modified continuously,
+check whether GAMA is resending the same static geometry every cycle.
+
+Workaround:
+
+- keep background species separate from dynamic species;
+- avoid sending unnecessary changing attributes for background geometry;
+- configure background appearance once in Unity preview;
+- hide dynamic species temporarily while checking the background;
+- if possible, send static/background geometry less frequently than dynamic
+  agents.
+
+A future improvement on the GAMA conversion side would be an explicit
+background-geometry option and a way to avoid repeatedly applying unchanged
+background visual data.
+
+## Too Many Debug Logs In Unity
+
+Very frequent `Debug.Log` calls can slow down Unity, especially when thousands
+of agents are updated.
+
+For user testing, use the `main` branch of the Unity package, where default
+logging is reduced.
+
+Use the `develop` branch only when collecting detailed logs for debugging.
+
+A future improvement would be a runtime **Developer/Debug mode** option instead
+of requiring a separate branch for verbose logs.
diff --git a/Documentation~/README.md b/Documentation~/README.md
index c7a50e1..1fe6ea8 100644
--- a/Documentation~/README.md
+++ b/Documentation~/README.md
@@ -15,12 +15,14 @@ documentation.
 - [4. Generate and configure the Unity preview](tutorial/04-generate-preview.md)
 - [5. Dynamic colors from GAMA attributes](tutorial/05-dynamic-colors.md)
 
+## Troubleshooting
+- [Troubleshooting](09-troubleshooting.md)
+
 ## Work in Progress
 - [Work in progress overview](work-in-progress/README.md)
 - [6. Configure species appearance](work-in-progress/06-configure-species.md)
 - [7. Apply preview settings in Play Mode](work-in-progress/07-apply-preview-settings.md)
 - [8. Optimize large simulations](work-in-progress/08-large-models-performance.md)
-- [9. Troubleshooting](work-in-progress/09-troubleshooting.md)
 - [User guide](user-guide/README.md)
 - [Technical documentation](technical/README.md)
 - [Runtime architecture notes](gama-unity.md)
diff --git a/Documentation~/images/tutorial/02-vr-generation-export-species-add.png b/Documentation~/images/tutorial/02-vr-generation-export-species-add.png
new file mode 100644
index 0000000..f71ff6b
Binary files /dev/null and b/Documentation~/images/tutorial/02-vr-generation-export-species-add.png differ
diff --git a/Documentation~/images/tutorial/02-vr-generation-export-species-final.png b/Documentation~/images/tutorial/02-vr-generation-export-species-final.png
new file mode 100644
index 0000000..3d985dc
Binary files /dev/null and b/Documentation~/images/tutorial/02-vr-generation-export-species-final.png differ
diff --git a/Documentation~/images/tutorial/02-vr-generation-general-parameters.png b/Documentation~/images/tutorial/02-vr-generation-general-parameters.png
new file mode 100644
index 0000000..fe27591
Binary files /dev/null and b/Documentation~/images/tutorial/02-vr-generation-general-parameters.png differ
diff --git a/Documentation~/images/tutorial/02-vr-generation-property-name.png b/Documentation~/images/tutorial/02-vr-generation-property-name.png
new file mode 100644
index 0000000..fe40738
Binary files /dev/null and b/Documentation~/images/tutorial/02-vr-generation-property-name.png differ
diff --git a/Documentation~/tutorial/00-gama-model-preparation.md b/Documentation~/tutorial/00-gama-model-preparation.md
index f9a3c8b..2280c1d 100644
--- a/Documentation~/tutorial/00-gama-model-preparation.md
+++ b/Documentation~/tutorial/00-gama-model-preparation.md
@@ -5,14 +5,16 @@ render the experiment.
 
 ## 0.1 GAMA Requirements
 
-Open your target VR-model in GAMA in the configuration of the screenshot below (ready to run). For explanations on how to install the Simple Unity Plugin, follow [this link](https://doc.project-simple.eu/gama/installation). 
+This tutorial requires a GAMA experiment converted into a Unity-compatible **vr_xp** experiment. This conversion is done with the **SIMPLE plugin**.
+
+Before continuing, make sure the **SIMPLE plugin** is installed in GAMA. Installation instructions are available [here](https://doc.project-simple.eu/gama/installation).
+
 > [!WARNING]
-> Don't forget to convert the experiment in "vr_xp", otherwise it will not work!!!
->
-> This step is explained [in this tutorial](https://doc.project-simple.eu/tutorials/Tutorial-Step-1)
+> Without the SIMPLE Unity plugin, you will not be able to convert the experiment to **vr_xp**, and Unity will not receive the simulation data correctly.
+
 
 ![Open a GAMA experiment](../images/tutorial/02-open-gama-experiment.png)
-_Exemple of an opened experiment in "Library models\Tutorials\Predator Prey\models"_
+_Example of the experiment that will be used throughout this tutorial_
 
 ## 0.2 Middleware Requirements
 
diff --git a/Documentation~/tutorial/02-first-experiment-launching.md b/Documentation~/tutorial/02-first-experiment-launching.md
index 6473974..ce65f5c 100644
--- a/Documentation~/tutorial/02-first-experiment-launching.md
+++ b/Documentation~/tutorial/02-first-experiment-launching.md
@@ -1,9 +1,9 @@
 # 2. Run the GAMA Experiment in Play Mode
 
-It is time to run the first GAMA experiment in Unity with this package. In this
-tutorial, use the 6th **Prey Predator** model located in the following hierarchy from GAMA.
+It is time to run the first GAMA experiment in Unity with this package. For this
+tutorial, use the **6th prey Predator** model located in the following hierarchy from GAMA.
 
-![Prey Predator 7 model location](../images/tutorial/02-prey-predator-7-location.png)
+![Prey Predator 6 model location](../images/tutorial/02-prey-predator-7-location.png)
 
 This experiment is used throughout the rest of the tutorial because it covers the
 main features provided by the package: static background species, dynamic agents,
@@ -13,11 +13,53 @@ This chapter validates the baseline live workflow: Unity enters Play Mode,
 connects to `simple.webplatform`, receives the running GAMA simulation, and
 creates Unity objects from the GAMA agents.
 
-## 2.1 Steps
+> [!WARNING]
+> The original GAMA experiment cannot be used directly in Unity. It must first be converted into a `vr_xp` experiment with the SIMPLE Unity plugin.
+
+## 2.1 Convert the GAMA Experiment to `vr_xp`
+
+Before running the model in Unity, convert the GAMA experiment with the SIMPLE Unity plugin. During this conversion, each species that should appear in Unity must be explicitly exported.
+
+On the first **Definition of the VR experiment** screen, keep the default values and click **Next**.
+
+![VR experiment general parameters](../images/tutorial/02-vr-generation-general-parameters.png)
+
+On the **Export species** screen, do not immediately click **Next**. Select a species on the left, then click the **+** button under **Aspect in Unity**.
+
+![Export species add one by one](../images/tutorial/02-vr-generation-export-species-add.png)
+
+Keep the default property name and click **OK**.
+
+![Keep default Unity property name](../images/tutorial/02-vr-generation-property-name.png)
+
+Repeat this for each species that must be visible in Unity, for example:
+
+- `prey`
+- `predator`
+- `vegetation_cell`
+
+At the end, these species should be marked as exported.
+
+![Final exported species selection](../images/tutorial/02-vr-generation-export-species-final.png)
+
+The `generic_species` entry is abstract and is not required for the visual result. Exporting it is harmless, but it can also be ignored.
+
+> [!IMPORTANT]
+> If the species are not added on the **Export species** screen, the experiment may still start in GAMA and the Unity player may be created, but no simulation agents will appear in Unity.
+
+After this, click **Next**, keep the default values, set the number of players between `0` and `1`, then click **Finish**.
+
+For more details, this step is explained [in this tutorial](https://doc.project-simple.eu/tutorials/Tutorial-Step-1)
+
+## 2.2 Steps
+
+> [!WARNING]
+> These steps must be followed **exactly in the order shown below**.  
+> If you change the order, the Unity connection may fail!!!
 
 1. Make sure the scene was prepared with **GAMA > GAMA Panel > Setup Scene**.
 2. Start `simple.webplatform` with  `npm start`
-3. Open and run the **Prey Predator 7** experiment in GAMA.
+3. Open and run the **vr_xp** version of **Prey Predator 6** in GAMA.
 
 ![Windows Overview](../images/tutorial/02-windows-overview-gama-unity.png)
 4. Press **Play** in Unity.
@@ -35,10 +77,10 @@ while the experiment is running.
 
 ![Runtime live overview](../images/tutorial/02-runtime-live-overview.png)
 
-## 2.2 Expected Result
+## 2.3 Expected Result
 
 During Play Mode, Unity should connect to `simple.webplatform` and create live
-Unity objects from the agents received from the **Prey Predator 7** model.
+Unity objects from the agents received from the **Prey Predator 6** model.
 
 The imported agents are grouped by species in the Unity hierarchy.
 
@@ -47,7 +89,7 @@ The imported agents are grouped by species in the Unity hierarchy.
 At this stage, the important result is that the connection works and that GAMA
 agents are imported into Unity while the experiment is running.
 
-## 2.3 Into the Next Step
+## 2.4 Into the Next Step
 
 This is already useful: we now have a functional connection between GAMA,
 `simple.webplatform`, and Unity. The preys, predators and vegetation cells agents are imported and
diff --git a/Documentation~/tutorial/05-dynamic-colors.md b/Documentation~/tutorial/05-dynamic-colors.md
index 9a417f9..f821225 100644
--- a/Documentation~/tutorial/05-dynamic-colors.md
+++ b/Documentation~/tutorial/05-dynamic-colors.md
@@ -9,7 +9,7 @@ the `food` attribute of each `vegetation_cell`: instead of showing every grass
 cell with the same green, Unity can use a more or less intense green depending
 on the `food` value, like in the GAMA display.
 
-## Attribute Requirements
+## 5.1 Attribute Requirements
 
 The GAMA model must send the attribute in `add_geometries_to_send(...)`.
 
@@ -33,20 +33,40 @@ map<string, list<float>> prey_atts <- ["energy":: prey_energy];
 do add_geometries_to_send(prey, up_prey, prey_atts);
 ```
 
-## Continuous Example: Vegetation Food
+## 5.2 Continuous Example: Vegetation Food
 
-Use this mode when an attribute is numeric and should produce a gradual visual
-change.
+### 5.2.1 Attributes Sent By GAMA
+Unity can only use dynamic color attributes that are sent by GAMA through the websocket.
+In this experiment, the `send_geometries` reflex sends the agents and geometries to Unity. By default, `vegetation_cell` is sent without its `food` attribute:
+```gaml
+do add_geometries_to_send(vegetation_cell, up_vegetation_cell);
+```
+To make `food` available in Unity, collect the `food` values and pass them as the third argument of `add_geometries_to_send`:
+```gaml
+list<float> grass_food <- vegetation_cell collect each.food;
+map<string, list<float>> grass_atts <- ["food":: grass_food];
+do add_geometries_to_send(vegetation_cell, up_vegetation_cell, grass_atts);
+```
+The complete reflex should look like this:
+```gaml
+reflex send_geometries {
+	list<float> grass_food <- vegetation_cell collect each.food;
+	map<string, list<float>> grass_atts <- ["food":: grass_food];
+	do add_geometries_to_send(prey, up_prey);
+	do add_geometries_to_send(predator, up_predator);
+	do add_geometries_to_send(vegetation_cell, up_vegetation_cell, grass_atts);
+	do add_geometries_to_send(generic_species, up_generic_species);
+}
+```
+> [!NOTE]
+> The key `food` is the attribute name that will be used later in Unity. This attribute must already exist on the GAMA `vegetation_cell` agents.
 
-In this example, the `vegetation_cell` species receives a numeric `food`
-attribute. The goal is:
 
-```text
-low food  -> lighter/darker green
-high food -> stronger green
-```
+### 5.2.2 Using The Attribute In Unity
+
+After generating the preview, Unity can use the `food` attribute sent by GAMA through the websocket.
 
-Steps:
+In this tutorial, to display the numeric attribute `food`, you should follow the next steps in the Edit mode of a preview :
 
 1. Select the `Game Manager`.
 2. In the Inspector, find `vegetation_cell`.
@@ -62,6 +82,16 @@ The numbered close-up below shows the important controls:
 
 ![Dynamic food color settings legend](../images/tutorial/05-dynamic-color-food-settings-legend.png)
 
+In this example, the `vegetation_cell` species receives a numeric `food` attribute. The goal is:
+
+```text
+low food  -> lighter/darker green
+high food -> stronger green
+```
+
+> [!NOTE]
+> Unity can only use attributes that were explicitly sent by GAMA. If `food` is not included in `add_geometries_to_send`, it will not be available in the Unity dynamic color settings.
+
 1. Open the **Dynamic Color** foldout.
 2. Enable the override.
 3. Choose **Continuous** mode.
@@ -85,7 +115,7 @@ stronger than high values.
 
 ![Food dynamic color with invert enabled](../images/tutorial/05-dynamic-color-preview-food-result.png)
 
-## Discrete Colors For States
+## 5.3 Discrete Colors For States
 
 For attributes that represent a small set of states, use **Discrete** mode
 instead. This is useful for experiments with states such as:
@@ -102,7 +132,7 @@ state = recovered    -> green
 state = dead         -> black
 ```
 
-## Runtime Behavior
+## 5.4 Runtime Behavior
 
 Dynamic colors are applied per agent when Unity receives GAMA attributes.
 
@@ -113,7 +143,7 @@ They do not replace the static preview workflow:
 - if the attribute is missing or cannot be parsed, Unity keeps the static/GAMA
   color instead of crashing.
 
-## Result
+## 5.4 Result
 
 At the end of this chapter, Unity should be able to show both static species
 settings and per-agent attribute variations, such as vegetation cells becoming
diff --git a/Documentation~/work-in-progress/09-troubleshooting.md b/Documentation~/work-in-progress/09-troubleshooting.md
deleted file mode 100644
index 2d18709..0000000
--- a/Documentation~/work-in-progress/09-troubleshooting.md
+++ /dev/null
@@ -1,84 +0,0 @@
-# 9. Troubleshooting
-
-This chapter lists common problems and the first checks to perform.
-
-## No Preview Is Generated
-
-Check:
-
-- `simple.webplatform` is running;
-- GAMA is running;
-- the experiment is open or selected;
-- the Unity middleware port is `8080`;
-- the model sends geometries through the Unity linker.
-
-> Screenshot to add: GAMA Panel state when preview generation fails.
-
-> Screenshot to add: middleware terminal or console showing whether
-> `simple.webplatform` is running.
-
-## Runtime Agents Do Not Appear
-
-Check the Unity console for:
-
-```text
-[GAMA][RUNTIME][CONNECTION]
-[GAMA][CONNECTION]
-[GAMA][RUNTIME][FLOW]
-```
-
-If Unity logs that the socket is not open, verify the middleware and connection
-settings.
-
-> Screenshot to add: Console filtered on `[GAMA][RUNTIME][CONNECTION]` and
-> `[GAMA][CONNECTION]`.
-
-> Screenshot to add: `Connection Manager` inspector with host and ports.
-
-## Colors Do Not Follow Attributes
-
-Check:
-
-- the GAMA model sends the attribute in `add_geometries_to_send(...)`;
-- Unity receives non-empty attributes;
-- the species dynamic color mode is enabled;
-- the selected attribute name matches the GAMA attribute key exactly;
-- discrete rules match the received values.
-
-> Screenshot to add: Dynamic Color setup next to a console log proving whether
-> attributes were received.
-
-## Prefab Does Not Change In Play Mode
-
-For Play Mode, the prefab should be loadable from a Unity `Resources` path.
-
-If a prefab is outside `Resources`, Edit Mode preview can use it, but runtime
-loading may fallback and log a warning.
-
-> Screenshot to add: prefab outside `Resources` warning in the console.
-
-## Scale Is Too Large In Play Mode
-
-Check:
-
-- the scale multiplier is not applied twice;
-- the species override asset contains the expected context-specific entry;
-- cell-like species keep their logical parent at scale `(1, 1, 1)`;
-- the visual child receives the visual scale.
-
-> Screenshot to add: inspector showing scale fields in the `Game Manager`.
-
-> Screenshot to add: hierarchy showing logical parent scale and visual child
-> scale.
-
-## Agents Freeze Or Accumulate
-
-For dynamic species, check that the live updates are complete or cumulative.
-Unity should remove dynamic agents only after a complete update confirms they are
-missing.
-
-Static/background species should not be pruned just because they are absent from
-a dynamic tick.
-
-> Optional GIF to add: predator/prey or dynamic agents disappearing and
-> appearing correctly during Play Mode.
diff --git a/Documentation~/work-in-progress/README.md b/Documentation~/work-in-progress/README.md
index e37b2f7..0e95d62 100644
--- a/Documentation~/work-in-progress/README.md
+++ b/Documentation~/work-in-progress/README.md
@@ -5,4 +5,3 @@ These tutorial chapters are not part of the stable tutorial flow yet.
 - [6. Configure species appearance](06-configure-species.md)
 - [7. Apply preview settings in Play Mode](07-apply-preview-settings.md)
 - [8. Optimize large simulations](08-large-models-performance.md)
-- [9. Troubleshooting](09-troubleshooting.md)