Readme -> Docs

Docs.md

@@ -0,0 +1,296 @@
+# 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 | ✅ |
+| `validate.py` — 23/23 checks pass | ✅ |
+
+---
+
+## 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.

README.md

@@ -1,320 +1,57 @@
-# 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_io` | — | −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`.
-
+title: Smart Contract Audit RL Environment
+emoji: 🔍
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+tags:
+  - openenv
+  - reinforcement-learning
+  - smart-contracts
+  - solidity
+  - security
+  - evaluation
+license: mit
+short_description: OpenEnv RL environment for smart contract security auditing
 ---
 
-## Project Structure
-
-```
-smart-contract-env/
-├── data/
-│   ├── contracts.json          # 4 contracts, 8 vulns, 11 properties, 8 rule episodes
-│   └── data_loader.py          # loaders for all three tasks
-├── env/
-│   ├── base_env.py             # Abstract OpenEnv base class
-│   └── schemas.py              # Typed Pydantic models (all ActionTypes)
-├── tasks/
-│   ├── task1/
-│   │   ├── environment.py      # Vulnerability detection environment
-│   │   └── grader.py           # Longest-match keyword grader (0/0.5/1.0)
-│   ├── task2/
-│   │   ├── environment.py      # Property discovery (one submit_property)
-│   │   └── grader.py           # Word-set + synonym grader (0.0–1.0)
-│   └── task3/
-│       ├── environment.py      # Rule checker (one submit_function)
-│       └── grader.py           # Three-tier grader (1.0/0.3/0.0)
-├── app.py                      # FastAPI — all OpenEnv HTTP endpoints
-├── inference.py                # Baseline LLM agent (all 3 tasks)
-├── eval.py                     # Oracle/partial/floor evaluation harness
-├── demo.py                     # Colourised scripted demos for all 3 tasks
-├── validate.py                 # 23-check pre-submission validator
-├── openenv.yaml                # Full OpenEnv spec metadata
-├── Dockerfile                  # Port 7860, healthcheck
-└── requirements.txt
-```
-
----
-
-## 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.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
-```
+# Smart Contract Audit RL Environment
 
----
+> OpenEnv-compliant RL environment for Solidity security analysis.
 
-## HTTP API
+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.
 
-| 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 |
+## Quick start
 
 ```bash
-# Full Task 3 episode
-curl -X POST localhost:7860/reset \
+# Reset — start a new episode
+curl -X POST $SPACE_URL/reset \
   -H "Content-Type: application/json" \
-  -d '{"task_id":"task3_rule_checker","seed":42}'
+  -d '{"task_id": "task1_vuln_detection", "seed": 42}'
 
-curl -X POST localhost:7860/step \
+# Step — list contract functions
+curl -X POST $SPACE_URL/step \
   -H "Content-Type: application/json" \
-  -d '{"action_type":"get_property_specification","params":{}}'
+  -d '{"action_type": "list_functions", "params": {}}'
 
-curl -X POST localhost:7860/step \
+# Submit answer
+curl -X POST $SPACE_URL/step \
   -H "Content-Type: application/json" \
-  -d '{"action_type":"submit_function","params":{"function_name":"emergencyDrain"}}'
+  -d '{"action_type": "submit", "params": {"function_name": "withdraw", "vulnerability_type": "reentrancy"}}'
 ```
 
----
-
-## 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 | ✅ |
-| `validate.py` — 23/23 checks pass | ✅ |
-
----
-
-## 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
-```
-
----
+## Endpoints
 
-## License
+| 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 |
 
-MIT. Contract vulnerability patterns adapted from Certora audits on production DeFi protocols.
+See the full [README](README.md) for detailed documentation.

SPACES_README.md

@@ -1,57 +0,0 @@
----
-title: Smart Contract Audit RL Environment
-emoji: 🔍
-colorFrom: blue
-colorTo: indigo
-sdk: docker
-app_port: 7860
-tags:
-  - openenv
-  - reinforcement-learning
-  - smart-contracts
-  - solidity
-  - security
-  - evaluation
-license: mit
-short_description: OpenEnv RL environment for smart contract security auditing
----
-
-# Smart Contract Audit RL Environment
-
-> OpenEnv-compliant RL environment for Solidity security analysis.
-
-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.
-
-## Quick start
-
-```bash
-# Reset — start a new episode
-curl -X POST $SPACE_URL/reset \
-  -H "Content-Type: application/json" \
-  -d '{"task_id": "task1_vuln_detection", "seed": 42}'
-
-# Step — list contract functions
-curl -X POST $SPACE_URL/step \
-  -H "Content-Type: application/json" \
-  -d '{"action_type": "list_functions", "params": {}}'
-
-# Submit 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.