feat: Add landing page and API documentation

- Implemented a landing page that serves HTML for browsers and JSON for API clients.
- Added a new index.html file containing detailed information about the Smart Contract Audit RL Environment, including tasks, data sources, and API endpoints.
- Updated the root endpoint to return the landing page or JSON summary based on the request's Accept header.
- Enhanced the project description and versioning in the root JSON response.

.gitignore

@@ -12,4 +12,5 @@ baseline_scores.json
 *.log
 .pytest_cache/
 MySolution.md
-nltk_data
+nltk_data
+uv.lock

Docs.md

@@ -1,295 +0,0 @@
-# Smart Contract Audit RL Environment
-
-> **OpenEnv-compliant reinforcement learning environment for smart contract security analysis.**
-> Three fully implemented tasks covering the core workflow of a professional Solidity auditor.
-
-[![OpenEnv Spec](https://img.shields.io/badge/OpenEnv-1.2-blue)](openenv.yaml)
-[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-brightgreen)](https://python.org)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)
-
----
-
-## Motivation
-
-Smart contract auditing is a $500M+ industry where human experts identify security flaws, write formal properties, and check whether code satisfies those properties. This environment lets agents practise exactly those three tasks using real Solidity contracts from Certora-audited DeFi projects.
-
----
-
-## Tasks at a Glance
-
-| # | Name | Difficulty | Status | One-line description |
-|---|------|-----------|--------|---------------------|
-| 1 | Targeted Vulnerability Detection | Medium | ✅ Active | Find which function is vulnerable and name the vulnerability |
-| 2 | Property Discovery | Hard | ✅ Active | Write the natural-language postcondition for a given function |
-| 3 | Rule Checker | Easy | ✅ Active | Identify which function violates a given property |
-
----
-
-## Task 1 — Targeted Vulnerability Detection *(Medium)*
-
-**Setup:** A Solidity contract (4–6 functions) is shown. One function contains a critical vulnerability.
-
-**Objective:** Name the vulnerable function and describe its vulnerability type in 2–3 words.
-
-### Actions
-
-| Action | Params | Reward |
-|--------|--------|--------|
-| `list_functions` | — | −0.05 |
-| `get_function_code` | `function_name` | +0.05 if target / −0.10 if other |
-| `get_function_summary` | `function_name` | +0.03 if target / −0.05 if other |
-| `get_file_metadata` | — | −0.04 |
-| `get_state_variable` | `variable_name` (opt.) | −0.05 |
-| `get_call_graph` | — | −0.08 |
-| `submit` | `function_name`, `vulnerability_type` | **+5.0 / +1.0 / −1.5** |
-
-Repeated queries: **−0.40**
-
-### Grader
-
-- **1.0** → correct function + correct vulnerability keyword → reward **+5.0**
-- **0.5** → correct function, vague/wrong vulnerability type → reward **+1.0**
-- **0.0** → wrong function → reward **−1.5**
-
-### Vulnerability types covered
-Reentrancy · Missing access control · Integer overflow · tx.origin authentication ·
-Front-running · Timestamp dependence · Denial of service · Unchecked return value
-
----
-
-## Task 2 — Property Discovery *(Hard)*
-
-**Setup:** A single Solidity function is shown. The agent must discover its natural-language correctness property.
-
-**Objective:** Write a precise 2–4 sentence postcondition describing what the function guarantees on success.
-
-### Actions
-
-| Action | Params | Reward |
-|--------|--------|--------|
-| `get_function_code` | — | −0.06 |
-| `get_function_natspec` | — | −0.08 |
-| `get_file_natspec` | — | −0.03 |
-| `get_related_functions` | — | −0.06 |
-| `get_signature` | — | −0.04 |
-| `get_similar_rule` | — | −0.20 |
-| `submit_property` | `property` (string) | **0.0–5.0** scored, ONE attempt |
-
-### Grader (keyword-weighted)
-
-```
-score  = 0.70 × (key_phrases_matched / total_key)
-       + 0.30 × (bonus_phrases_matched / total_bonus)
-reward = score × 5.0
-```
-
-Matching uses **word-set containment + synonym expansion** — words don't need to be adjacent.
-
----
-
-## Task 3 — Rule Checker *(Easy)*
-
-**Setup:** A Solidity contract is shown alongside a violated property in natural English. One function breaks that property.
-
-**Objective:** Identify which function violates the property.
-
-### Actions
-
-| Action | Params | Reward |
-|--------|--------|--------|
-| `list_functions` | — | −0.05 |
-| `get_function_metadata` | `function_name` | −0.05 |
-| `get_function_code` | `function_name` | −0.10 |
-| `get_state_variable` | `variable_name` (opt.) | −0.05 |
-| `get_call_graph` | — | −0.08 |
-| `get_property_specification` | — | **−0.03** (cheapest — read this first!) |
-| `submit_function` | `function_name` | **+5.0 / +1.5 / −1.5**, ONE attempt |
-
-### Grader (three-tier deterministic)
-
-- **1.0** → exact target function (case-insensitive) → reward **+5.0**
-- **0.3** → a direct internal subfunction of the target → reward **+1.5**
-- **0.0** → anything else → reward **−1.5**
-
-`get_property_specification` returns the precise pre/post-condition (`rule_broken_specs`). Reading it costs only −0.03 and usually provides enough information to identify the violating function without inspecting all code.
-
----
-
-## Observation Space
-
-All tasks share the same `Observation` structure:
-
-```json
-{
-  "task_id": "task3_rule_checker",
-  "contract_name": "SimpleVault",
-  "contract_description": "An ETH vault that allows users to deposit...",
-  "available_actions": ["list_functions", "get_function_metadata", "..."],
-  "last_action": "get_property_specification",
-  "last_action_result": "Formal property:\nPre: caller != owner...",
-  "step_count": 1,
-  "cumulative_reward": -0.03,
-  "done": false,
-  "extra": {
-    "property_english": "Only the owner should be able to drain the vault...",
-    "solidity_version": "0.8.0",
-    "hint": "Find the function that violates this property..."
-  }
-}
-```
-
-For Task 2, `extra` contains `target_function` and `target_signature`.
-For Task 3, `extra` contains `property_english`.
-
----
-
-## Project Structure
-
-```
-
-```
-
----
-
-## Setup
-
-### Local Python
-
-```bash
-pip install -r requirements.txt
-
-# Start the server
-python app.py                     # → http://localhost:7860
-
-# Interactive / scripted demos
-python demo.py --auto             # Task 1 scripted demo
-python demo.py --auto --seed 42   # Task 2 (same flag, different env seed)
-
-# Full evaluation harness (no LLM required)
-python eval.py                    # All 3 tasks, 8 episodes each
-python eval.py --task 3           # Task 3 only
-python eval.py --episodes 16 --verbose
-
-# Pre-submission validation
-python validate-submission.py                # 23/23 checks
-```
-
-### Docker
-
-```bash
-docker build -t sc-audit-env .
-docker run -p 7860:7860 sc-audit-env
-```
-
-### Direct Python API
-
-```python
-# Task 3 example
-from tasks.task3.environment import Task3Environment
-from env.schemas import Action, ActionType
-
-env = Task3Environment()
-r = env.reset(seed=42)
-print(r.observation.extra["property_english   "])
-# "Only the owner should be able to drain the vault..."
-
-s = env.step(Action(action_type=ActionType.GET_PROPERTY_SPECIFICATION))
-s = env.step(Action(action_type=ActionType.SUBMIT_FUNCTION,
-             params={"function_name": "emergencyDrain"}))
-print(s.reward.value)  # +5.0
-```
-
----
-
-## HTTP API
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `GET` | `/health` | Liveness probe |
-| `GET` | `/tasks` | All tasks + status |
-| `POST` | `/reset` | Start episode (`task_id`, `seed`) |
-| `POST` | `/step` | Take action (`action_type`, `params`) |
-| `GET` | `/state` | Internal debug state |
-| `GET` | `/action_space?task_id=...` | Action schema |
-| `GET` | `/observation_space` | Observation schema |
-
-```bash
-# Full Task 3 episode
-curl -X POST localhost:7860/reset \
-  -H "Content-Type: application/json" \
-  -d '{"task_id":"task3_rule_checker","seed":42}'
-
-curl -X POST localhost:7860/step \
-  -H "Content-Type: application/json" \
-  -d '{"action_type":"get_property_specification","params":{}}'
-
-curl -X POST localhost:7860/step \
-  -H "Content-Type: application/json" \
-  -d '{"action_type":"submit_function","params":{"function_name":"emergencyDrain"}}'
-```
-
----
-
-## Baseline Inference
-
-```bash
-export API_BASE_URL="https://api.openai.com/v1"
-export MODEL_NAME="gpt-4o-mini"
-export HF_TOKEN="sk-..."
-python inference.py
-```
-
-### Expected scores (gpt-4o-mini, 3 episodes per task)
-
-| Task | Avg Grader Score | Notes |
-|------|-----------------|-------|
-| Task 1 | ~0.67 | Good at classic vulns; struggles with subtle ones |
-| Task 2 | ~0.55 | Reasonable properties; misses specific variable names |
-| Task 3 | ~0.78 | Property text gives strong signal; usually correct in 3–4 steps |
-
----
-
-## Evaluation Summary
-
-Deterministic oracle / partial / floor tiers verified on 8 episodes (seeds 42–49):
-
-| Task | Oracle | Partial/Sub | Floor | Ordering |
-|------|--------|-------------|-------|----------|
-| Task 1 | **1.000** | 0.500 | 0.000 | ✅ 1.0 > 0.5 > 0.0 |
-| Task 2 | **0.775** | 0.034 | 0.000 | ✅ 0.775 > 0.034 > 0.0 |
-| Task 3 | **1.000** | 0.037 | 0.000 | ✅ 1.0 > 0.037 > 0.0 |
-
-The clear separation across all three tasks confirms the graders provide **meaningful gradient signal** across the full reward range — a core requirement for RL training environments.
-
----
-
-## OpenEnv Spec Compliance
-
-| Requirement | Status |
-|-------------|--------|
-| Typed `Observation`, `Action`, `Reward` Pydantic models | ✅ |
-| `step(action) → StepResult(obs, reward, done, info)` | ✅ |
-| `reset() → ResetResult` | ✅ |
-| `state() → StateResult` | ✅ |
-| `openenv.yaml` metadata | ✅ |
-| 3 tasks, all active | ✅ |
-| Grader scores in [0.0, 1.0] | ✅ |
-| Shaped rewards (non-binary signal) | ✅ |
-| Dockerfile + port 7860 | ✅ |
-| `inference.py` with OpenAI client | ✅ |
-
----
-
-## Deploying to Hugging Face Spaces
-
-```bash
-# Copy the HF frontmatter into README.md, then:
-git remote add hf https://huggingface.co/spaces/<user>/<space>
-git push hf main
-```
-
----
-
-## License
-
-MIT. Contract vulnerability patterns adapted from Certora audits on production DeFi protocols.

LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2011-2026 The Bootstrap Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -12,46 +12,410 @@ tags:
   - solidity
   - security
   - evaluation
+  - openenv
 license: mit
 short_description: OpenEnv RL environment for smart contract security auditing
 ---
 
-# Smart Contract Audit RL Environment
+# 🔍 Smart Contract Audit RL Environment
+
+> An OpenEnv-compliant reinforcement learning environment for training and evaluating AI agents on real-world Solidity smart contract security auditing tasks.
+
+---
+
+## Overview
+
+Smart contract auditing is a high-stakes, expert-level task performed by professional security researchers. Mistakes cost millions — the Ethereum ecosystem has lost over **$3 billion** to exploits in audited and unaudited contracts alike. This environment simulates the core reasoning loop of a smart contract auditor, enabling RL agents to learn structured exploration strategies for vulnerability detection, property discovery, and rule checking.
+
+The dataset is derived from real audit reports published by **[Certora](https://www.certora.com/)**, covering three production-grade DeFi protocols:
+
+| Source | Protocol |
+|---|---|
+| Certora Audit | AaveVault |
+| Certora Audit | AaveVaultV2 |
+| Certora Audit | Lido Finance |
+
+Each episode exposes a fragment of a real Solidity contract. The agent must use a structured action API — mirroring how a human auditor would methodically inspect a codebase — to accomplish a defined objective within a fixed step budget.
+
+---
+
+## Environment Architecture
+
+```
+SmartContractEnv/
+├── agents/
+│   ├── task1.py
+│   ├── task2.py
+│   └── task3.py
+├── data/
+│   ├── __init__.py
+│   ├── contracts.json
+│   ├── data_loader.py
+│   ├── properties.csv
+│   ├── Template.json
+│   ├── vulnerabilities.json
+│   └── vulnerabilities.md
+├── env/
+│   ├── __init__.py
+│   ├── base_env.py
+│   └── schemas.py
+├── server/
+│   ├── tasks/
+│   │   ├── task1/
+│   │   │   ├── __init__.py
+│   │   │   ├── actions.py
+│   │   │   ├── environment.py
+│   │   │   └── grader.py
+│   │   ├── task2/
+│   │   │   ├── __init__.py
+│   │   │   ├── actions.py
+│   │   │   ├── environment.py
+│   │   │   └── grader.py
+│   │   ├── task3/
+│   │   │   ├── __init__.py
+│   │   │   ├── actions.py
+│   │   │   ├── environment.py
+│   │   │   └── grader.py
+│   │   └── __init__.py
+│   ├── __init__.py
+│   └── app.py
+├── utils/
+│   ├── __init__.py
+│   ├── prompts.py
+│   ├── propertyretriever.py
+│   └── semanticmatcher.py
+├── .env
+├── .gitignore
+├── demo.py
+├── Dockerfile
+├── Docs.md
+├── eval.py
+├── inference.py
+├── LICENSE.txt
+├── openenv.yaml
+├── pyproject.toml
+├── README.md
+├── requirements.txt
+└── validate-submission.sh
+```
+
+---
+
+## Tasks
+
+### Task 1 — Targeted Vulnerability Detection *(Medium)*
+
+**Real-world analogue:** A security auditor is handed a Solidity file and asked to pinpoint the vulnerable function and describe the class of bug.
+
+**Setup:** The agent receives a single Solidity file. The episode selects one vulnerable function at random from the dataset (7–8 available) on each `reset()`.
+
+**Objective:** Identify the vulnerable function and describe its issue in 2–3 words (e.g., `"reentrancy"`, `"integer overflow"`, `"unchecked return value"`). Submit `"NO"` if no vulnerability exists.
+
+**Action Space:**
+
+| Action | Reward | Notes |
+|---|---|---|
+| `list_functions` | −0.05 | Returns all function signatures in the file |
+| `get_function_code` | −0.10 (wrong fn) / +0.05 (correct fn) | Returns raw Solidity source of one function |
+| `get_function_summary` | −0.05 (wrong) / +0.03 (correct) | Returns NatSpec comments for a function |
+| `get_file_metadata` | −0.04 | Returns the file's header comment / pragma / imports |
+| `get_state_variables` | −0.05 | Returns all contract-level state variable declarations |
+| `get_call_graph` | −0.08 | Returns the inter-function call graph |
+| `get_task_state` | 0.00 | Returns current step count and cumulative reward |
+| `submit` | +5.00 (correct) / −1.50 (wrong) | One submission allowed per episode |
+| *(repeated query)* | −0.40 | Penalty for querying the exact same action+params twice |
+| *(unknown action)* | −0.20 | Any unrecognised action type |
+
+**Episode terminates** on `submit` or when the step budget is exhausted.
+
+---
+
+### Task 2 — Property Discovery *(Hard)*
+
+**Real-world analogue:** A formal verification engineer must derive an invariant or safety property for a contract function — the kind written as a Certora Verification Language (CVL) spec.
+
+**Setup:** The agent receives a single function extracted from a Solidity file, along with a brief description of the broader contract. The episode targets a function that has a known, labelled property in the dataset.
+
+**Objective:** Produce a natural-language description of the function's key safety property (e.g., *"The total shares minted must never exceed the total underlying assets deposited"*).
+
+**Action Space:**
+
+| Action | Reward | Notes |
+|---|---|---|
+| `get_file_natspec` | −0.03 | File-level NatSpec documentation |
+| `get_function_natspec` | −0.08 | Function-level NatSpec comments |
+| `get_function_code` | −0.06 | Raw Solidity source of the target function |
+| `get_related_functions` | −0.06 | Functions that call or are called by the target |
+| `get_input_output` | −0.04 | Parameter names/types and return values |
+| `get_similar_property` | −0.20 | Hard-coded reference property from a different contract |
+| `submit_property` | 0–5 (graded) | **One attempt per episode.** Scored by deterministic similarity checker |
+
+**Grading:** Submission reward is computed by a deterministic checker that combines keyword overlap and structural similarity against the ground-truth property. Score is normalised to `[0, 5]` and then scaled to `[0.0, 1.0]` for the episode return.
+
+---
+
+### Task 3 — Rule Checker *(Easy)*
+
+**Real-world analogue:** Given a known security rule (e.g., *"functions that transfer funds must emit a Transfer event"*), identify which function in the contract violates it.
+
+**Setup:** The agent receives a Solidity file and a natural-language description of a property/rule. At least one function in the file violates this rule.
+
+**Objective:** Identify the name of the rule-breaking function.
+
+**Action Space:**
+
+| Action | Reward | Notes |
+|---|---|---|
+| `get_property_specification` | −0.03 | Returns a pseudo-formal (CVL-like) version of the property |
+| `list_functions` | −0.05 | All function signatures in the file |
+| `get_function_metadata` | −0.05 | Visibility, modifiers, and signature for a function |
+| `get_function_code` | −0.10 | Raw Solidity source of one function |
+| `get_state_variables` | −0.05 | Contract-level state variable declarations |
+| `get_call_graph` | −0.08 | Inter-function call graph |
+| `submit` | +5.00 (exact) / +1.50 (sub-caller) / −1.50 (wrong) | One submission per episode |
+
+**Partial credit:** If the agent names a function that *calls* the true violating function, it receives +1.50 rather than the full +5.00. This rewards reasoning that reaches the right area of the call graph.
+
+---
+
+## Reward Design
+
+Rewards are shaped to encourage **efficient, targeted exploration** and discourage two failure modes: aimless browsing and brute-force guessing.
+
+```
+R_episode = Σ(step_rewards) + final_submission_reward
+```
+
+- **Exploration costs** are small and graduated by information value — cheap actions (metadata) cost less than expensive ones (full code retrieval).
+- **Correct-direction bonuses** on `get_function_code` in Task 1 reward navigating toward the vulnerable function before committing.
+- **Repetition penalty** (−0.40) discourages looping over the same queries.
+- **Wrong submission** (−1.50) is painful enough to deter random guessing but recoverable through efficient prior exploration.
+- **Episode score** is normalised to `[0.0, 1.0]` for the OpenEnv grader: `score = max(0, R_episode) / 5.0`.
+
+---
+
+## Observation Space
+
+Every `step()` and `reset()` returns a typed `Observation` object:
+
+```python
+class Observation(BaseModel):
+    task_id: str                        # "task1_vuln_detection" | "task2_property_discovery" | "task3_rule_checker"
+    step: int                           # Current step index (0-indexed)
+    max_steps: int                      # Episode step budget
+    cumulative_reward: float            # Running reward total
+    done: bool                          # Episode terminal flag
+    content: str                        # Main textual payload (code, summary, error, etc.)
+    metadata: dict[str, Any]            # Extra context (function name, contract name, etc.)
+    initial_description: str            # Persistent contract/task description shown every step
+```
+
+---
+
+## Action Space
 
-> OpenEnv-compliant RL environment for Solidity security analysis.
+Actions are typed `Action` objects passed to `step()`:
 
-This Space exposes the full OpenEnv HTTP interface for **Task 1: Targeted Vulnerability Detection**.
-Agents explore Solidity contracts using a structured action API and identify vulnerable functions.
+```python
+class Action(BaseModel):
+    action_type: str                    # One of the action names listed per task above
+    params: dict[str, str]             # e.g. {"function_name": "withdraw"}
+```
+
+All unknown `action_type` values return a penalty observation without terminating the episode.
+
+---
+
+## OpenEnv Interface
+
+The environment exposes a standard HTTP API:
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/health` | Liveness probe — returns `{"status": "ok"}` |
+| `GET` | `/tasks` | Lists all tasks with ID, difficulty, and status |
+| `POST` | `/reset` | Starts a new episode. Body: `{"task_id": str, "seed": int}` |
+| `POST` | `/step` | Takes one action. Body: `{"action_type": str, "params": {}}` |
+| `GET` | `/state` | Returns full internal episode state (debug) |
+| `GET` | `/action_space` | Returns JSON schema of valid actions |
+| `GET` | `/observation_space` | Returns JSON schema of observation structure |
 
-## Quick start
+### Quick Start
 
 ```bash
-# Reset — start a new episode
+SPACE_URL=http://localhost:7860
+
+# Start a new episode for Task 1
 curl -X POST $SPACE_URL/reset \
   -H "Content-Type: application/json" \
   -d '{"task_id": "task1_vuln_detection", "seed": 42}'
 
-# Step — list contract functions
+# List all functions in the contract
 curl -X POST $SPACE_URL/step \
   -H "Content-Type: application/json" \
   -d '{"action_type": "list_functions", "params": {}}'
 
-# Submit answer
+# Inspect a specific function
+curl -X POST $SPACE_URL/step \
+  -H "Content-Type: application/json" \
+  -d '{"action_type": "get_function_code", "params": {"function_name": "withdraw"}}'
+
+# Submit your answer
 curl -X POST $SPACE_URL/step \
   -H "Content-Type: application/json" \
   -d '{"action_type": "submit", "params": {"function_name": "withdraw", "vulnerability_type": "reentrancy"}}'
 ```
 
-## Endpoints
+---
 
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/health` | Liveness probe |
-| GET | `/tasks` | All tasks + status |
-| POST | `/reset` | New episode |
-| POST | `/step` | Take action |
-| GET | `/state` | Debug state |
-| GET | `/action_space` | Action schema |
-| GET | `/observation_space` | Observation schema |
-
-See the full [README](README.md) for detailed documentation.
+## Setup & Installation
+
+### Prerequisites
+
+- Docker ≥ 20.10
+- Python 3.11+ (for local development)
+- `OPENAI_API_KEY`, `API_BASE_URL`, `MODEL_NAME`, `HF_TOKEN` environment variables
+
+### Run with Docker
+
+```bash
+# Build the image
+docker build -t sc-audit-env .
+
+# Run the container
+docker run -p 7860:7860 \
+  -e OPENAI_API_KEY=$OPENAI_API_KEY \
+  -e API_BASE_URL=$API_BASE_URL \
+  -e MODEL_NAME=$MODEL_NAME \
+  sc-audit-env
+
+# Verify it's running
+curl http://localhost:7860/health
+```
+
+### Run Locally (Development)
+
+```bash
+pip install -r requirements.txt
+uvicorn api.app:app --host 0.0.0.0 --port 7860 --reload
+```
+
+### Validate OpenEnv Compliance
+
+```bash
+openenv validate openenv.yaml
+```
+
+---
+
+## Baseline Inference Script
+
+The `inference.py` script runs an OpenAI-compatible model against all three tasks and reports episode scores. It reads credentials from environment variables and completes in under 20 minutes on a 2 vCPU / 8 GB machine.
+
+```bash
+export OPENAI_API_KEY=your_key
+export API_BASE_URL=https://api.openai.com/v1   # or your custom endpoint
+export MODEL_NAME=gpt-4o-mini
+
+python inference.py
+```
+
+**Expected output:**
+
+```
+=== Smart Contract Audit RL — Baseline Evaluation ===
+
+Task 1 | Targeted Vulnerability Detection  | Score: 0.41 | Steps used: 8/15
+Task 2 | Property Discovery                | Score: 0.28 | Steps used: 6/10
+Task 3 | Rule Checker                      | Score: 0.72 | Steps used: 4/10
+
+Overall average: 0.47
+```
+
+> **Note:** Scores are stochastic due to random episode selection on `reset()`. Run with a fixed seed (`--seed 42`) for reproducible results.
+
+### Agent System Prompt
+
+The inference script injects the following system prompt to guide output format:
+
+```
+You are a smart contract security auditor. You will be given access to a Solidity
+contract via a structured action API. Use the available actions to investigate the
+contract, then submit your answer.
+
+Always respond with a single JSON object:
+{"action_type": "<action>", "params": {"<key>": "<value>"}}
+
+Do not include any other text outside the JSON object.
+```
+
+---
+
+## openenv.yaml
+
+```yaml
+name: smart-contract-audit-env
+version: "1.0.0"
+description: >
+  OpenEnv RL environment for Solidity smart contract security auditing.
+  Agents explore real-world DeFi contracts using a structured action API
+  to detect vulnerabilities, discover properties, and check rule compliance.
+tasks:
+  - id: task1_vuln_detection
+    name: Targeted Vulnerability Detection
+    difficulty: medium
+    max_steps: 15
+    max_score: 5.0
+  - id: task2_property_discovery
+    name: Property Discovery
+    difficulty: hard
+    max_steps: 10
+    max_score: 5.0
+  - id: task3_rule_checker
+    name: Rule Checker
+    difficulty: easy
+    max_steps: 10
+    max_score: 5.0
+observation_schema: models/observation.py
+action_schema: models/action.py
+app_port: 7860
+```
+
+---
+
+## Data
+
+The dataset (`data/dataset.json`) contains **7–8 labelled entries** per contract, each with format accoding to `data/template.json`:
+Ground truth is **never exposed** to the agent via any action. The `submit` action is the only path to positive reward.
+
+---
+
+## Design Notes & Known Limitations
+
+- **Reward calibration:** Step penalties and submission rewards may need tuning based on empirical agent performance. Current values are derived from initial design rationale, not from extensive ablation.
+- **Call graph granularity:** The current `get_call_graph` action returns the entire graph at once. A future revision could expose it incrementally (per-function neighbours) to make the action more informative and cost-proportional.
+- **Vulnerability naming:** Vulnerability types do not follow a fixed taxonomy. Grading uses keyword + semantic matching against a curated synonym list (e.g., `"re-entrancy"` ≡ `"reentrancy"`).
+- **Dataset size:** The current dataset covers 3 contracts with 7–8 vulnerabilities each. Expanding to more Certora audit reports would improve task diversity and reduce overfitting risk.
+- **`get_function_code` decomposition:** This action could be split into finer-grained sub-actions (`get_parameters`, `get_return_values`, `get_modifiers`) to give agents a more gradual information ladder.
+- **Property similarity scoring (Task 2):** Sentence transformer models cannot be used in the containerised environment due to memory constraints. The checker instead uses TF-IDF cosine similarity combined with keyword matching against the ground-truth property.
+
+---
+
+## License
+
+MIT — see `LICENSE` for details.
+
+Data sourced from public Certora audit reports. Solidity source files are reproduced for research and evaluation purposes.
+
+---
+
+## Citation
+
+```bibtex
+@misc{sc-audit-openenv-2025,
+  title   = {Smart Contract Audit RL Environment},
+  year    = {2025},
+  note    = {OpenEnv-compliant RL environment for Solidity security analysis.
+             Data sourced from Certora audit reports (AaveVault, AaveVaultV2, Lido Finance).}
+}
+```

server/app.py

@@ -17,8 +17,10 @@ If omitted, "default" is used (fine for sequential single-agent runs).
 """
 
 from typing import Dict, Optional, Union
+from zipfile import Path
 
-from fastapi import FastAPI, HTTPException, Query
+from fastapi import FastAPI, HTTPException, Query, Request
+from fastapi.responses import FileResponse, JSONResponse
 from pydantic import BaseModel
 
 from env.schemas import Action, ActionType, TaskInfo
@@ -75,6 +77,32 @@ class ResetRequest(BaseModel):
 class StepRequest(BaseModel):
     action_type: str
     params: dict = {}
+    
+
+_ROOT_JSON = {
+    "name": "Smart Contract Audit RL Environment",
+    "version": "1.2.0",
+    "description": (
+        "OpenEnv-compliant RL environment for Solidity smart contract security analysis. "
+        "Train and evaluate agents on real-world DeFi audit tasks from Certora reports."
+    ),
+    "tasks": [
+        {"id": "task1_vuln_detection",     "name": "Targeted Vulnerability Detection", "difficulty": "medium"},
+        {"id": "task2_property_discovery", "name": "Property Discovery",                "difficulty": "hard"},
+        {"id": "task3_rule_checker",       "name": "Rule Checker",                      "difficulty": "easy"},
+    ],
+    "endpoints": {
+        "reset":             "POST /reset",
+        "step":              "POST /step",
+        "state":             "GET  /state",
+        "tasks":             "GET  /tasks",
+        "health":            "GET  /health",
+        "action_space":      "GET  /action_space",
+        "observation_space": "GET  /observation_space",
+        "docs":              "GET  /docs",
+    },
+    "data_sources": ["AaveVault", "AaveVaultV2", "Lido Finance"],
+}
 
 
 # ─────────────────────────────────────────────────────────────────────────────
@@ -82,8 +110,16 @@ class StepRequest(BaseModel):
 # ─────────────────────────────────────────────────────────────────────────────
 
 @app.get("/")
-def root():
-    return {"message": "Welcome to the Smart Contract Audit RL Environment! Visit README.md for documentation."}
+def root(request: Request):
+    """
+    Landing page.
+    - Browsers (Accept: text/html)  → polished HTML UI
+    - API clients (Accept: */*)     → JSON summary
+    """
+    accept = request.headers.get("accept", "")
+    if "text/html" in accept and Path("./index.html").is_file():
+        return FileResponse("./index.html", media_type="text/html", status_code=200)
+    return JSONResponse(content=_ROOT_JSON, status_code=200)
 
 @app.get("/health")
 def health():

server/index.html

@@ -0,0 +1,708 @@
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Landing page HTML
+# ─────────────────────────────────────────────────────────────────────────────
+
+LANDING_HTML = """<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>SC Audit RL Environment</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link href="https://fonts.googleapis.com/css2?family=Space+Mono:wght@400;700&family=DM+Sans:wght@300;400;500&display=swap" rel="stylesheet" />
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+    :root {
+      --bg:        #0a0c0f;
+      --surface:   #111418;
+      --border:    #1e2530;
+      --accent:    #00ff88;
+      --accent2:   #00b8ff;
+      --warn:      #ffaa00;
+      --danger:    #ff4455;
+      --text:      #c8d0dc;
+      --muted:     #4a5568;
+      --mono:      'Space Mono', monospace;
+      --sans:      'DM Sans', sans-serif;
+    }
+
+    html { scroll-behavior: smooth; }
+
+    body {
+      background: var(--bg);
+      color: var(--text);
+      font-family: var(--sans);
+      font-size: 15px;
+      line-height: 1.6;
+      min-height: 100vh;
+      overflow-x: hidden;
+    }
+
+    /* ── noise overlay ── */
+    body::before {
+      content: '';
+      position: fixed; inset: 0;
+      background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='0.04'/%3E%3C/svg%3E");
+      pointer-events: none;
+      z-index: 0;
+      opacity: .5;
+    }
+
+    /* ── grid lines ── */
+    body::after {
+      content: '';
+      position: fixed; inset: 0;
+      background-image:
+        linear-gradient(var(--border) 1px, transparent 1px),
+        linear-gradient(90deg, var(--border) 1px, transparent 1px);
+      background-size: 40px 40px;
+      pointer-events: none;
+      z-index: 0;
+      opacity: .35;
+    }
+
+    /* ─── layout ─── */
+    .wrap { position: relative; z-index: 1; max-width: 1100px; margin: 0 auto; padding: 0 28px; }
+
+    /* ─── header ─── */
+    header {
+      border-bottom: 1px solid var(--border);
+      padding: 18px 0;
+    }
+    .nav {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+    }
+    .logo {
+      font-family: var(--mono);
+      font-size: 13px;
+      color: var(--accent);
+      letter-spacing: .05em;
+      display: flex;
+      align-items: center;
+      gap: 8px;
+    }
+    .logo-dot {
+      width: 8px; height: 8px;
+      border-radius: 50%;
+      background: var(--accent);
+      box-shadow: 0 0 8px var(--accent);
+      animation: pulse 2s ease-in-out infinite;
+    }
+    @keyframes pulse {
+      0%,100% { opacity: 1; }
+      50% { opacity: .35; }
+    }
+    .nav-links {
+      display: flex;
+      gap: 24px;
+      list-style: none;
+    }
+    .nav-links a {
+      font-family: var(--mono);
+      font-size: 11px;
+      color: var(--muted);
+      text-decoration: none;
+      letter-spacing: .08em;
+      text-transform: uppercase;
+      transition: color .2s;
+    }
+    .nav-links a:hover { color: var(--accent); }
+
+    /* ─── hero ─── */
+    .hero {
+      padding: 90px 0 70px;
+      position: relative;
+    }
+    .hero-tag {
+      font-family: var(--mono);
+      font-size: 11px;
+      color: var(--accent);
+      letter-spacing: .12em;
+      text-transform: uppercase;
+      margin-bottom: 22px;
+      display: flex;
+      align-items: center;
+      gap: 10px;
+    }
+    .hero-tag::before {
+      content: '';
+      display: inline-block;
+      width: 28px; height: 1px;
+      background: var(--accent);
+    }
+    h1 {
+      font-family: var(--mono);
+      font-size: clamp(28px, 5vw, 52px);
+      font-weight: 700;
+      line-height: 1.15;
+      color: #fff;
+      margin-bottom: 26px;
+      letter-spacing: -.02em;
+    }
+    h1 span {
+      color: var(--accent);
+      text-shadow: 0 0 30px rgba(0,255,136,.3);
+    }
+    .hero-sub {
+      font-size: 16px;
+      color: var(--muted);
+      max-width: 560px;
+      line-height: 1.7;
+      margin-bottom: 40px;
+    }
+    .hero-badges {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 10px;
+      margin-bottom: 44px;
+    }
+    .badge {
+      font-family: var(--mono);
+      font-size: 11px;
+      padding: 5px 12px;
+      border-radius: 3px;
+      letter-spacing: .06em;
+    }
+    .badge-green  { background: rgba(0,255,136,.08); color: var(--accent);  border: 1px solid rgba(0,255,136,.25); }
+    .badge-blue   { background: rgba(0,184,255,.08); color: var(--accent2); border: 1px solid rgba(0,184,255,.25); }
+    .badge-yellow { background: rgba(255,170,0,.08);  color: var(--warn);   border: 1px solid rgba(255,170,0,.25); }
+
+    .cta-row { display: flex; gap: 14px; flex-wrap: wrap; }
+    .btn {
+      font-family: var(--mono);
+      font-size: 12px;
+      padding: 11px 22px;
+      border-radius: 4px;
+      text-decoration: none;
+      letter-spacing: .06em;
+      transition: all .2s;
+      cursor: pointer;
+      border: none;
+    }
+    .btn-primary {
+      background: var(--accent);
+      color: #000;
+      font-weight: 700;
+    }
+    .btn-primary:hover {
+      background: #fff;
+      box-shadow: 0 0 24px rgba(0,255,136,.4);
+    }
+    .btn-outline {
+      background: transparent;
+      color: var(--text);
+      border: 1px solid var(--border);
+    }
+    .btn-outline:hover {
+      border-color: var(--accent);
+      color: var(--accent);
+    }
+
+    /* ─── section ─── */
+    section { padding: 64px 0; border-top: 1px solid var(--border); }
+    .section-label {
+      font-family: var(--mono);
+      font-size: 10px;
+      color: var(--muted);
+      letter-spacing: .14em;
+      text-transform: uppercase;
+      margin-bottom: 36px;
+    }
+    h2 {
+      font-family: var(--mono);
+      font-size: 22px;
+      font-weight: 700;
+      color: #fff;
+      margin-bottom: 8px;
+    }
+    h3 {
+      font-family: var(--mono);
+      font-size: 14px;
+      color: #fff;
+      margin-bottom: 10px;
+    }
+
+    /* ─── task cards ─── */
+    .task-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
+      gap: 18px;
+      margin-top: 32px;
+    }
+    .task-card {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      padding: 26px;
+      position: relative;
+      overflow: hidden;
+      transition: border-color .25s, transform .25s;
+    }
+    .task-card:hover {
+      border-color: var(--accent);
+      transform: translateY(-3px);
+    }
+    .task-card::before {
+      content: '';
+      position: absolute;
+      top: 0; left: 0; right: 0;
+      height: 2px;
+    }
+    .task-card.easy::before   { background: var(--accent); }
+    .task-card.medium::before { background: var(--warn); }
+    .task-card.hard::before   { background: var(--danger); }
+
+    .task-header {
+      display: flex;
+      justify-content: space-between;
+      align-items: flex-start;
+      margin-bottom: 14px;
+    }
+    .task-num {
+      font-family: var(--mono);
+      font-size: 11px;
+      color: var(--muted);
+    }
+    .diff-badge {
+      font-family: var(--mono);
+      font-size: 10px;
+      padding: 3px 9px;
+      border-radius: 99px;
+      letter-spacing: .07em;
+      text-transform: uppercase;
+    }
+    .diff-easy   { background: rgba(0,255,136,.1);  color: var(--accent); }
+    .diff-medium { background: rgba(255,170,0,.1);   color: var(--warn); }
+    .diff-hard   { background: rgba(255,68,85,.1);   color: var(--danger); }
+
+    .task-desc {
+      font-size: 13px;
+      color: var(--muted);
+      line-height: 1.65;
+      margin-bottom: 18px;
+    }
+    .task-actions {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 6px;
+    }
+    .action-chip {
+      font-family: var(--mono);
+      font-size: 10px;
+      padding: 3px 8px;
+      border-radius: 3px;
+      background: rgba(255,255,255,.04);
+      color: var(--muted);
+      border: 1px solid var(--border);
+    }
+
+    /* ─── endpoints table ─── */
+    .endpoint-list { margin-top: 28px; display: flex; flex-direction: column; gap: 2px; }
+    .endpoint-row {
+      display: grid;
+      grid-template-columns: 70px 220px 1fr;
+      gap: 16px;
+      align-items: center;
+      padding: 12px 18px;
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: 4px;
+      font-size: 13px;
+      transition: border-color .2s;
+    }
+    .endpoint-row:hover { border-color: var(--muted); }
+    .method {
+      font-family: var(--mono);
+      font-size: 11px;
+      font-weight: 700;
+      padding: 3px 8px;
+      border-radius: 3px;
+      text-align: center;
+      letter-spacing: .04em;
+    }
+    .method-get  { background: rgba(0,184,255,.12); color: var(--accent2); }
+    .method-post { background: rgba(0,255,136,.12); color: var(--accent); }
+    .path { font-family: var(--mono); font-size: 13px; color: #fff; }
+    .ep-desc { color: var(--muted); font-size: 13px; }
+
+    /* ─── code block ─── */
+    .code-wrap {
+      margin-top: 28px;
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      overflow: hidden;
+    }
+    .code-header {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      padding: 10px 18px;
+      border-bottom: 1px solid var(--border);
+    }
+    .code-title { font-family: var(--mono); font-size: 11px; color: var(--muted); }
+    .copy-btn {
+      font-family: var(--mono);
+      font-size: 10px;
+      color: var(--muted);
+      background: none;
+      border: 1px solid var(--border);
+      border-radius: 3px;
+      padding: 3px 10px;
+      cursor: pointer;
+      transition: all .2s;
+    }
+    .copy-btn:hover { color: var(--accent); border-color: var(--accent); }
+    pre {
+      margin: 0;
+      padding: 22px;
+      overflow-x: auto;
+      font-family: var(--mono);
+      font-size: 12px;
+      line-height: 1.75;
+      color: var(--text);
+    }
+    .kw  { color: var(--accent2); }
+    .str { color: var(--accent); }
+    .cm  { color: var(--muted); }
+    .pn  { color: var(--warn); }
+
+    /* ─── data sources ─── */
+    .source-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+      gap: 16px;
+      margin-top: 28px;
+    }
+    .source-card {
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      padding: 22px;
+      display: flex;
+      gap: 16px;
+      align-items: flex-start;
+    }
+    .source-icon {
+      font-size: 22px;
+      flex-shrink: 0;
+      line-height: 1;
+    }
+    .source-name {
+      font-family: var(--mono);
+      font-size: 13px;
+      color: #fff;
+      margin-bottom: 4px;
+    }
+    .source-meta { font-size: 12px; color: var(--muted); }
+
+    /* ─── footer ─── */
+    footer {
+      border-top: 1px solid var(--border);
+      padding: 28px 0;
+      margin-top: 40px;
+    }
+    .footer-inner {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      flex-wrap: wrap;
+      gap: 14px;
+    }
+    .footer-left { font-family: var(--mono); font-size: 11px; color: var(--muted); }
+    .footer-links { display: flex; gap: 20px; }
+    .footer-links a {
+      font-family: var(--mono);
+      font-size: 11px;
+      color: var(--muted);
+      text-decoration: none;
+      transition: color .2s;
+    }
+    .footer-links a:hover { color: var(--accent); }
+
+    /* ─── responsive ─── */
+    @media (max-width: 600px) {
+      .endpoint-row { grid-template-columns: 60px 1fr; }
+      .ep-desc { display: none; }
+      .nav-links { display: none; }
+    }
+
+    /* ─── fade-in ─── */
+    .fade-in {
+      opacity: 0;
+      transform: translateY(18px);
+      animation: fadeUp .55s ease forwards;
+    }
+    @keyframes fadeUp {
+      to { opacity: 1; transform: none; }
+    }
+    .fade-in:nth-child(1) { animation-delay: .05s; }
+    .fade-in:nth-child(2) { animation-delay: .12s; }
+    .fade-in:nth-child(3) { animation-delay: .19s; }
+    .fade-in:nth-child(4) { animation-delay: .26s; }
+  </style>
+</head>
+<body>
+
+<!-- ── HEADER ──────────────────────────────────────────────── -->
+<header>
+  <div class="wrap">
+    <nav class="nav">
+      <div class="logo">
+        <span class="logo-dot"></span>
+        SC-AUDIT-ENV v1.2.0
+      </div>
+      <ul class="nav-links">
+        <li><a href="#tasks">Tasks</a></li>
+        <li><a href="#api">API</a></li>
+        <li><a href="#quickstart">Quickstart</a></li>
+        <li><a href="/docs">Swagger</a></li>
+      </ul>
+    </nav>
+  </div>
+</header>
+
+<!-- ── HERO ────────────────────────────────────────────────── -->
+<div class="wrap">
+  <div class="hero">
+    <div class="hero-tag fade-in">OpenEnv · Reinforcement Learning · Smart Contract Security</div>
+    <h1 class="fade-in">Audit Solidity.<br><span>Train smarter agents.</span></h1>
+    <p class="hero-sub fade-in">
+      An OpenEnv-compliant RL environment for smart contract security analysis.
+      Agents explore real-world DeFi contracts from Certora audit reports —
+      detecting vulnerabilities, deriving properties, and checking invariants.
+    </p>
+    <div class="hero-badges fade-in">
+      <span class="badge badge-green">openenv</span>
+      <span class="badge badge-blue">solidity</span>
+      <span class="badge badge-blue">aave</span>
+      <span class="badge badge-blue">lido</span>
+      <span class="badge badge-yellow">certora</span>
+      <span class="badge badge-green">3 tasks</span>
+    </div>
+    <div class="cta-row fade-in">
+      <a class="btn btn-primary" href="/docs">Explore API Docs</a>
+      <a class="btn btn-outline" href="#quickstart">Quick Start →</a>
+    </div>
+  </div>
+</div>
+
+<!-- ── TASKS ───────────────────────────────────────────────── -->
+<section id="tasks">
+  <div class="wrap">
+    <div class="section-label">// three tasks</div>
+    <h2>What can agents learn here?</h2>
+    <p style="color:var(--muted); max-width:520px; margin-top:6px;">
+      Each task mirrors a real step in a professional smart contract audit.
+      Difficulty is graded easy → medium → hard.
+    </p>
+
+    <div class="task-grid">
+      <!-- Task 1 -->
+      <div class="task-card medium">
+        <div class="task-header">
+          <span class="task-num">TASK 01</span>
+          <span class="diff-badge diff-medium">medium</span>
+        </div>
+        <h3>Targeted Vulnerability Detection</h3>
+        <p class="task-desc">
+          Given a Solidity file, identify the vulnerable function and name the
+          vulnerability class in 2–3 words. Submit <code>NO</code> if no vulnerability exists.
+        </p>
+        <div class="task-actions">
+          <span class="action-chip">list_functions</span>
+          <span class="action-chip">get_function_code</span>
+          <span class="action-chip">get_state_variable</span>
+          <span class="action-chip">get_call_graph</span>
+          <span class="action-chip">submit</span>
+        </div>
+      </div>
+
+      <!-- Task 2 -->
+      <div class="task-card hard">
+        <div class="task-header">
+          <span class="task-num">TASK 02</span>
+          <span class="diff-badge diff-hard">hard</span>
+        </div>
+        <h3>Property Discovery</h3>
+        <p class="task-desc">
+          Given a single function, derive its natural-language safety property —
+          the kind a formal verification engineer would write as a CVL invariant.
+          One submission attempt per episode, scored 0–5.
+        </p>
+        <div class="task-actions">
+          <span class="action-chip">get_function_natspec</span>
+          <span class="action-chip">get_related_functions</span>
+          <span class="action-chip">get_similar_rule</span>
+          <span class="action-chip">submit_property</span>
+        </div>
+      </div>
+
+      <!-- Task 3 -->
+      <div class="task-card easy">
+        <div class="task-header">
+          <span class="task-num">TASK 03</span>
+          <span class="diff-badge diff-easy">easy</span>
+        </div>
+        <h3>Rule Checker</h3>
+        <p class="task-desc">
+          A property is given in plain English. At least one function in the
+          contract breaks it. Find the offender. Partial credit for naming a
+          direct caller of the true violating function.
+        </p>
+        <div class="task-actions">
+          <span class="action-chip">list_functions</span>
+          <span class="action-chip">get_function_code</span>
+          <span class="action-chip">get_property_specification</span>
+          <span class="action-chip">submit_function</span>
+        </div>
+      </div>
+    </div>
+  </div>
+</section>
+
+<!-- ── DATA SOURCES ────────────────────────────────────────── -->
+<section>
+  <div class="wrap">
+    <div class="section-label">// dataset</div>
+    <h2>Grounded in real audits</h2>
+    <p style="color:var(--muted); max-width:520px; margin-top:6px;">
+      All contracts and vulnerabilities are sourced from public Certora audit
+      reports on production DeFi protocols.
+    </p>
+    <div class="source-grid">
+      <div class="source-card">
+        <div class="source-icon">🏦</div>
+        <div>
+          <div class="source-name">AaveVault</div>
+          <div class="source-meta">Certora Audit · ERC-4626 vault · Access control, share accounting</div>
+        </div>
+      </div>
+      <div class="source-card">
+        <div class="source-icon">🏦</div>
+        <div>
+          <div class="source-name">AaveVaultV2</div>
+          <div class="source-meta">Certora Audit · Upgraded vault · Fee logic, reentrancy surfaces</div>
+        </div>
+      </div>
+      <div class="source-card">
+        <div class="source-icon">🔷</div>
+        <div>
+          <div class="source-name">Lido Finance</div>
+          <div class="source-meta">Certora Audit · Liquid staking · Rebasing token invariants</div>
+        </div>
+      </div>
+    </div>
+  </div>
+</section>
+
+<!-- ── API REFERENCE ───────────────────────────────────────── -->
+<section id="api">
+  <div class="wrap">
+    <div class="section-label">// http interface</div>
+    <h2>API Endpoints</h2>
+    <div class="endpoint-list">
+      <div class="endpoint-row">
+        <span class="method method-get">GET</span>
+        <span class="path">/health</span>
+        <span class="ep-desc">Liveness probe</span>
+      </div>
+      <div class="endpoint-row">
+        <span class="method method-get">GET</span>
+        <span class="path">/tasks</span>
+        <span class="ep-desc">List all tasks with difficulty and status</span>
+      </div>
+      <div class="endpoint-row">
+        <span class="method method-post">POST</span>
+        <span class="path">/reset</span>
+        <span class="ep-desc">Start a new episode &mdash; body: <code>{task_id, seed}</code></span>
+      </div>
+      <div class="endpoint-row">
+        <span class="method method-post">POST</span>
+        <span class="path">/step</span>
+        <span class="ep-desc">Take one action &mdash; body: <code>{action_type, params}</code></span>
+      </div>
+      <div class="endpoint-row">
+        <span class="method method-get">GET</span>
+        <span class="path">/state</span>
+        <span class="ep-desc">Full internal episode state (debug)</span>
+      </div>
+      <div class="endpoint-row">
+        <span class="method method-get">GET</span>
+        <span class="path">/action_space</span>
+        <span class="ep-desc">Valid actions for a task &mdash; query: <code>?task_id=</code></span>
+      </div>
+      <div class="endpoint-row">
+        <span class="method method-get">GET</span>
+        <span class="path">/observation_space</span>
+        <span class="ep-desc">Observation schema (all tasks share this)</span>
+      </div>
+      <div class="endpoint-row">
+        <span class="method method-get">GET</span>
+        <span class="path">/docs</span>
+        <span class="ep-desc">Interactive Swagger UI</span>
+      </div>
+    </div>
+  </div>
+</section>
+
+<!-- ── QUICK START ─────────────────────────────────────────── -->
+<section id="quickstart">
+  <div class="wrap">
+    <div class="section-label">// quick start</div>
+    <h2>Run an episode in 3 calls</h2>
+    <div class="code-wrap">
+      <div class="code-header">
+        <span class="code-title">bash</span>
+        <button class="copy-btn" onclick="copyCode(this)">copy</button>
+      </div>
+      <pre id="snippet"><span class="cm"># 1. Reset — start Task 1 with a fixed seed</span>
+<span class="kw">curl</span> -X POST $SPACE_URL/reset \
+  -H <span class="str">"Content-Type: application/json"</span> \
+  -d <span class="str">'{"task_id": "task1_vuln_detection", "seed": 42}'</span>
+
+<span class="cm"># 2. Explore — list all functions in the contract</span>
+<span class="kw">curl</span> -X POST $SPACE_URL/step \
+  -H <span class="str">"Content-Type: application/json"</span> \
+  -d <span class="str">'{"action_type": "list_functions", "params": {}}'</span>
+
+<span class="cm"># 3. Submit — name the vulnerable function</span>
+<span class="kw">curl</span> -X POST $SPACE_URL/step \
+  -H <span class="str">"Content-Type: application/json"</span> \
+  -d <span class="str">'{"action_type": "submit", "params": {"function_name": "withdraw", "vulnerability_type": "reentrancy"}}'</span></pre>
+    </div>
+  </div>
+</section>
+
+<!-- ── FOOTER ──────────────────────────────────────────────── -->
+<footer>
+  <div class="wrap">
+    <div class="footer-inner">
+      <div class="footer-left">
+        SC-AUDIT-ENV &nbsp;·&nbsp; MIT License &nbsp;·&nbsp; Data from Certora public audits
+      </div>
+      <div class="footer-links">
+        <a href="/docs">Swagger</a>
+        <a href="/tasks">Tasks JSON</a>
+        <a href="/health">Health</a>
+      </div>
+    </div>
+  </div>
+</footer>
+
+<script>
+  function copyCode(btn) {
+    const pre = document.getElementById('snippet');
+    const text = pre.innerText;
+    navigator.clipboard.writeText(text).then(() => {
+      btn.textContent = 'copied!';
+      setTimeout(() => btn.textContent = 'copy', 2000);
+    });
+  }
+</script>
+</body>
+</html>"""