diff --git a/README.md b/README.md
index e652f73..54cea6a 100644
--- a/README.md
+++ b/README.md
@@ -41,40 +41,62 @@ No additional dependencies are required beyond NumPy.
 
 ```
 MetaMo-Python/
-|-- core/                    # Core state representations and configuration
-|   |-- __init__.py
-|   |-- config.py            # System parameters, goal/modulator constants
-|   |-- state.py             # MotivationalState, Stimulus, Action dataclasses
+|-- core/                         # Core state representations and configuration
+|   |-- config.py                 # System parameters, goal/modulator constants
+|   |-- state.py                  # MotivationalState, Stimulus, Action dataclasses
+|   |-- engine.py                 # MetaMoEngine: full pipeline orchestration
 |
-|-- category/                # Category theory abstractions
-|   |-- __init__.py
-|   |-- functors.py          # AppraisalComonad and DecisionMonad base classes
-|   |-- bimonad.py           # MetaMoPseudoBimonad implementation
+|-- category/                     # Category theory abstractions
+|   |-- functors.py               # AppraisalComonad, DecisionMonad, TranslationFunctor
+|   |-- bimonad.py                # MetaMoPseudoBimonad implementation
 |
-|-- openpsi/                 # OpenPsi appraisal layer
-|   |-- __init__.py
-|   |-- appraisal.py         # OpenPsiAppraisal comonad implementation
+|-- openpsi/                      # OpenPsi appraisal layer
+|   |-- appraisal.py              # OpenPsiAppraisal comonad implementation
 |
-|-- magus/                   # MAGUS decision layer
-|   |-- __init__.py
-|   |-- decision.py          # MagusDecision monad implementation
+|-- magus/                        # MAGUS decision layer
+|   |-- decision.py               # MagusDecision monad implementation
 |
-|-- llm/                     # LLM integration layer
-|   |-- __init__.py
-|   |-- client.py            # LLM client wrapper
-|   |-- conversation.py      # Conversation and context management
-|   |-- prompts.py           # Prompt templates
-|   |-- parser.py            # Response parsing
+|-- llm/                          # LLM integration layer
+|   |-- client.py                 # Gemini client, stimulus/candidate generation
+|   |-- conversation.py           # Conversational memory and response generation
+|   |-- prompts.py                # Prompt templates for appraisal and planning
+|   |-- parser.py                 # JSON response parsing
+|   |-- action_schema.py          # Action vocabulary and execution instructions
 |
-|-- dynamics/                # Stability and coherence mechanisms
-|   |-- __init__.py
-|   |-- coherence.py        # State blending and self-model drift checking
-|   |-- stability.py        # Safe region detection and contractivity validation
+|-- dynamics/                     # Stability and coherence mechanisms
+|   |-- coherence.py              # State blending and self-model drift checking
+|   |-- stability.py              # Safe region detection and contractivity validation
 |
-|-- applications/            # Example applications
-|   |-- __init__.py
-|   |-- research_assistant.py  # Demo: MetaMo-powered research assistant
+|-- applications/                 # Research assistant application
+|   |-- research_assistant.py     # MetaMo-powered research assistant REPL
+|   |-- papers/                   # Paper ingestion and context management
+|       |-- entities.py           # DocumentChunk, Paper dataclasses
+|       |-- services/             # Extractors, chunker, storage, ingestion, context
 |
+|-- usecase/                      # GridWorld simulation use case
+|   |-- agents/
+|   |   |-- baseline_agent.py     # Tabular Q-learning, no motivational layer
+|   |   |-- metamo_agent.py       # Q-learning + MetaMo motivational regulation
+|   |-- environment/
+|   |   |-- gridworld.py          # 10x10 GridWorld with lava and mineral spawns
+|   |-- metamo/
+|   |   |-- core.py               # Adapter: stimulus, candidates, consensus, transition
+|   |   |-- state.py              # Initial motivational state for the GridWorld agent
+|   |-- metrics/
+|   |   |-- collector.py          # EpisodeLog, MetricsCollector, SRV and recovery metrics
+|   |-- simulation/
+|   |   |-- main.py               # Pygame event loop (entry point)
+|   |   |-- runner.py             # Training loop and episode lifecycle helpers
+|   |   |-- renderer.py           # All pygame drawing: grids, panels, overlays
+|   |   |-- plots.py              # Evaluation plot export
+|   |-- assets/                   # Agent sprite, mineral sprite, sound
+|   |-- plot/                     # Generated evaluation plots (created at runtime)
+|   |-- INTEGRATION.md            # GridWorld integration documentation
+|
+|-- setup.sh                      # Setup script for Linux/macOS
+|-- setup.ps1                     # Setup script for Windows
+|-- .env.example                  # Environment variable template
+|-- requirements.txt
 |-- README.md
 |-- LICENSE
 ```
diff --git a/requirements.txt b/requirements.txt
index bcc3471..666004c 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,5 +1,3 @@
 numpy
-google-genai
-dotenv
 pygame
-matplotlib
+matplotlib
\ No newline at end of file
diff --git a/setup.ps1 b/setup.ps1
new file mode 100644
index 0000000..505f3ab
--- /dev/null
+++ b/setup.ps1
@@ -0,0 +1,41 @@
+$ErrorActionPreference = "Stop"
+$VenvDir = ".venv"
+
+# check if python exists
+$pythonExists = Get-Command python -ErrorAction SilentlyContinue
+if (-not $pythonExists) {
+    Write-Host "Error: python not found. Install Python 3 first."
+    exit 1
+}
+
+# check if we are in the right folder
+if (-not (Test-Path "requirements.txt")) {
+    Write-Host "Error: no requirements.txt found in $(Get-Location)."
+    exit 1
+}
+
+# create the venv if it doesn't exist
+if (-not (Test-Path $VenvDir)) {
+    Write-Host "Creating virtual environment in $VenvDir ..."
+    python -m venv $VenvDir
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host "Failed to create the virtual environment."
+        exit 1
+    }
+} else {
+    Write-Host "'$VenvDir' already exists, creation skipped."
+}
+
+# activate the venv
+$activateScript = Join-Path $VenvDir "Scripts\Activate.ps1"
+. $activateScript
+
+Write-Host "Upgrading pip ..."
+python -m pip install --upgrade pip
+
+Write-Host "Installing dependencies from requirements.txt ..."
+pip install -r requirements.txt
+
+Write-Host "Setup complete."
+Write-Host "Activate with: .\$VenvDir\Scripts\Activate.ps1"
+Write-Host "Run with: python usecase\simulation\main.py"
\ No newline at end of file
diff --git a/setup.sh b/setup.sh
new file mode 100644
index 0000000..8bf21ce
--- /dev/null
+++ b/setup.sh
@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+VENV_DIR=".venv"
+
+# check if python exists
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "Error: python3 not found. Install Python 3 first."
+  exit 1
+fi
+
+# check if we are in the right folder
+if [[ ! -f "requirements.txt" ]]; then
+  echo "Error: no requirements.txt found in $(pwd)."
+  exit 1
+fi
+
+# create the venv if it doesn't exist
+if [[ ! -d "$VENV_DIR" ]]; then
+  echo "Creating virtual environment in $VENV_DIR ..."
+  if ! python3 -m venv "$VENV_DIR" 2>/tmp/venv_error.log; then
+    if grep -qi "ensurepip" /tmp/venv_error.log; then
+      echo "The 'venv' module isn't installed for python3."
+      echo "On Ubuntu/Debian, run: sudo apt update && sudo apt install python3-venv"
+    else
+      cat /tmp/venv_error.log
+    fi
+    rm -f /tmp/venv_error.log
+    exit 1
+  fi
+  rm -f /tmp/venv_error.log
+else
+  echo "'$VENV_DIR' already exists, creation skipped."
+fi
+
+# activate the venv
+source "$VENV_DIR/bin/activate"
+
+echo "Upgrading pip ..."
+pip install --upgrade pip
+
+echo "Installing dependencies from requirements.txt ..."
+pip install -r requirements.txt
+
+echo "Setup complete."
+echo "Activate with: source $VENV_DIR/bin/activate"
+echo "Run with: python usecase/simulation/main.py"
\ No newline at end of file