@r1z4x/tezgah 1.0.0

package/skills/rl-env/SOURCE

@@ -0,0 +1,41 @@
+# Source
+
+Vendored from https://github.com/adithya-s-k/FineEnvs at
+`26ab9c60915005b6f536968ac0928482bb18c0f8` (2026-10-01), Apache-2.0 licence (the
+repository's root `LICENSE`). Every body below is byte-for-byte upstream,
+frontmatter included, at its upstream path under `.claude/skills/`. Checkout for
+a re-vendor: `git clone https://github.com/adithya-s-k/FineEnvs && git -C <clone>
+checkout 26ab9c60915005b6f536968ac0928482bb18c0f8`.
+
+## What is vendored
+
+The five environment-authoring skills and every reference file they ship: 14
+files - four framework ports and the orchestrator that drives them from a
+description. The entry point `skills/rl-env/SKILL.md` is tezgah's own and is not
+part of the manifest; neither is this file. Upstream's own install route
+(`npx skills add adithya-s-k/FineEnvs`) is not used: it writes into a host's
+skill directory, which is outside tezgah's router, its install report and this
+manifest.
+
+## Manifest
+
+One row per vendored file: its path under `skills/rl-env/`, the path it came from
+upstream, and the sha256 of the bytes as vendored - so a body that drifts from
+what was vetted is visible.
+
+| file | upstream path | sha256 |
+|---|---|---|
+| `generate-nemo-gym-env/SKILL.md` | `.claude/skills/generate-nemo-gym-env/SKILL.md` | `b051de706519973d23e1acb9211f7dee18a681b2b94f0fdc132c6cab0c035f3e` |
+| `generate-nemo-gym-env/references/architecture.md` | `.claude/skills/generate-nemo-gym-env/references/architecture.md` | `2329797c0881697c56d8dfee62396fb858bcfac3c313840155b23acf6720a77c` |
+| `generate-openenv-env/SKILL.md` | `.claude/skills/generate-openenv-env/SKILL.md` | `f8d7d65ec85ee228bf8ffe15df72492c5043541c853f287c5159d7b3eea383c9` |
+| `generate-openenv-env/references/architecture.md` | `.claude/skills/generate-openenv-env/references/architecture.md` | `6ba32c5a1498c6660f79db3feeb0f49226344054bae7cdc1d84d8440147d5509` |
+| `generate-ors-env/SKILL.md` | `.claude/skills/generate-ors-env/SKILL.md` | `68385ef145bdcff61d2878be6db1d6b9652581ba7a5a05369ce6a61a6332ace5` |
+| `generate-ors-env/references/architecture.md` | `.claude/skills/generate-ors-env/references/architecture.md` | `ee87650a409a8ae375935a99daa9a5141d1fae514a1d05abcd87293759e708e4` |
+| `generate-verifiers-env/SKILL.md` | `.claude/skills/generate-verifiers-env/SKILL.md` | `afd9c6d0521735acfed0f308a133e33a6b3d24534e79aabb659f8f20ccfc7a64` |
+| `generate-verifiers-env/references/architecture.md` | `.claude/skills/generate-verifiers-env/references/architecture.md` | `babda38780715a82f9b481ef4469221c8752befb5f9bf1dc7d9093f2b05d634e` |
+| `rl-env-from-description/SKILL.md` | `.claude/skills/rl-env-from-description/SKILL.md` | `fb2b92b92988655b4c4ddae5cfe07e58f18d4105fef4e21058925e48a680438b` |
+| `rl-env-from-description/references/interview.md` | `.claude/skills/rl-env-from-description/references/interview.md` | `8284ef8b809d6bcbbd76c9bee63baf1e23aae80a4f089d7daed02ec6cc285e9a` |
+| `rl-env-from-description/references/nemo_gym.md` | `.claude/skills/rl-env-from-description/references/nemo_gym.md` | `48e2b011ad13454e38245dcb791a98a6496c1ea53cc909895e2350d50a303e74` |
+| `rl-env-from-description/references/openenv.md` | `.claude/skills/rl-env-from-description/references/openenv.md` | `4550337161bac2e08fbf5ca6a5b58ca55c422cc06169669a784a9eb974e35bd6` |
+| `rl-env-from-description/references/ors.md` | `.claude/skills/rl-env-from-description/references/ors.md` | `f409b75446e510b3837d770cebb592ff7dca0130def913f40ca427854aae1710` |
+| `rl-env-from-description/references/verifiers.md` | `.claude/skills/rl-env-from-description/references/verifiers.md` | `761d8ff1f776cc16e485141e00fd5c6da5b9264d601dfa1787bd97f3657dfb46` |

package/skills/rl-env/generate-nemo-gym-env/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: generate-nemo-gym-env
+description: Builds a NeMo Gym (NVIDIA) variant of an RL environment. Use whenever someone asks to scaffold a NeMo Gym Resources Server, port an existing env to NeMo Gym, expose tools as `app.post()` endpoints with cookie-based sessions, add a post-episode `/verify` reward grader, or deploy a NeMo Gym env to HF Spaces. NeMo Gym is the right framework when the user wants HTTP+REST with cookie session handling, raw `requests`-driven rollouts (no SDK client), Ray-based orchestration, or NVIDIA NeMo / TRL training integration with a `responses_create_params` + `ground_truth` dataset format. Output is a runnable `<env_dir>/nemo_gym/` folder with `server.py`, `pyproject.toml`, `Dockerfile`, `configs/<env>.yaml`, and `rollout.py`. Use for prompts like "wrap my env in NeMo Gym", "make a NeMo resources server for X", or "add a post-episode grader to my env".
+---
+
+# generate-nemo-gym-env
+
+Build the NeMo Gym variant of an env. NeMo Gym is NVIDIA's RL gym layer, optimized for Ray-based orchestration and post-episode grading. The Python package is `nemo_gym` (installed via `pip install git+https://github.com/NVIDIA-NeMo/Gym`).
+
+## Concept
+
+NeMo Gym is NVIDIA's RL gym layer for LLM agents. It's built on Ray and ships a FastAPI-based `SimpleResourcesServer` that exposes one `POST /<tool>` endpoint per tool, plus the standard `/seed_session` (cookie-based session bootstrap) and `/verify` (post-episode grader). Targets [docs.nvidia.com/nemo/gym/latest](https://docs.nvidia.com/nemo/gym/latest/).
+
+When the user has a shared domain module (`<domain>.py`) and wants a NeMo Gym variant, wrap it. Don't duplicate logic.
+
+## Archetypes
+
+| Archetype | Hallmarks |
+|---|---|
+| **Pure-Python game** | Single tool endpoint; `/verify` does substring match against `ground_truth`. |
+| **Stateful sandbox** | Per-session sandbox in `self.sessions`; lazy init on first tool call. |
+| **Vision / computer-use** | One endpoint per action; `/verify` rewards trajectories that called `terminate(success)`. |
+
+## Recommended file layout
+
+The user picks the actual paths. The canonical shape:
+
+```
+<env_dir>/nemo_gym/
+├── pyproject.toml         # nemo_gym (git+) + e2b-* + fastapi + uvicorn + requests
+├── __init__.py
+├── Dockerfile             # Ray-aware multi-stage
+├── configs/<env>.yaml     # NeMo Gym config (entrypoint, domain, description)
+├── server.py              # SimpleResourcesServer subclass with tool endpoints
+├── rollout.py             # raw requests + cookie session
+└── README.md
+```
+
+Note: NeMo Gym requires **Python 3.12+**.
+
+## Implementation order
+
+### 1. Server class — `server.py`
+
+```python
+from nemo_gym.base_resources_server import (
+    BaseResourcesServerConfig,
+    BaseSeedSessionRequest, BaseSeedSessionResponse,
+    BaseVerifyRequest, BaseVerifyResponse,
+    SimpleResourcesServer,
+)
+from nemo_gym.server_utils import SESSION_ID_KEY
+from fastapi import FastAPI, Request
+from pydantic import BaseModel, Field
+from typing import Any, Dict
+
+class MyConfig(BaseResourcesServerConfig):
+    pass
+
+class GuessReq(BaseModel):
+    word: str
+
+class ToolResponse(BaseModel):
+    output: str
+
+class MyVerifyRequest(BaseVerifyRequest):
+    ground_truth: list = []
+
+class MyResourcesServer(SimpleResourcesServer):
+    config: MyConfig
+    sessions: Dict[str, Dict[str, Any]] = Field(default_factory=dict)
+
+    def setup_webserver(self) -> FastAPI:
+        app = super().setup_webserver()
+        app.post("/guess")(self.guess)
+        return app
+
+    async def seed_session(self, body: BaseSeedSessionRequest) -> BaseSeedSessionResponse:
+        return BaseSeedSessionResponse()
+
+    def _sess(self, request: Request) -> Dict[str, Any]:
+        sid = request.session[SESSION_ID_KEY]
+        if sid not in self.sessions:
+            self.sessions[sid] = {"game": WordleGame(), "step": 0}
+        return self.sessions[sid]
+
+    async def guess(self, body: GuessReq, request: Request) -> ToolResponse:
+        sess = self._sess(request)
+        feedback = sess["game"].guess(body.word)
+        sess["step"] += 1
+        return ToolResponse(output=feedback)
+
+    async def verify(self, body: MyVerifyRequest) -> BaseVerifyResponse:
+        # Compute reward from the response trajectory + ground truth
+        expected = ""
+        if body.ground_truth and isinstance(body.ground_truth, list):
+            expected = body.ground_truth[0].get("expected_output", "")
+        reward = 0.0
+        for item in body.response.output:
+            if hasattr(item, "type") and item.type == "function_call_output":
+                if expected and expected in getattr(item, "output", ""):
+                    reward = 1.0; break
+        return BaseVerifyResponse(**body.model_dump(), reward=reward)
+
+if __name__ == "__main__":
+    MyResourcesServer.run_webserver()
+```
+
+Key contracts:
+- **One endpoint per tool.** Register them in `setup_webserver()`. Pydantic models on the request body become the JSON shape.
+- **Sessions live in `self.sessions`** keyed by `request.session[SESSION_ID_KEY]`. Lazy-init on first call. NeMo Gym sets the session cookie on `POST /seed_session`.
+- **`verify()` is the grader.** Read `body.ground_truth` (passed by the trainer) and `body.response.output` (the trajectory). Return `BaseVerifyResponse(**body.model_dump(), reward=...)`.
+
+### 2. NeMo Gym config — `configs/<name>.yaml`
+
+```yaml
+my_env_resources_server:
+  resources_servers:
+    my_env:
+      entrypoint: server.py
+      domain: agent
+      description: "What this env does"
+```
+
+This is the file the NeMo Gym CLI looks for when launching via `ng_run "+config_paths=[configs/my_env.yaml]"`.
+
+### 3. Rollout — `rollout.py`
+
+NeMo Gym has **no Python client SDK**. The rollout speaks raw HTTP via `requests` with a `Session` for cookie persistence:
+
+```python
+import requests
+session = requests.Session()
+session.post(f"{ENV_URL}/seed_session", json={}).raise_for_status()
+r = session.post(f"{ENV_URL}/guess", json={"word": "crane"})
+result = r.json()["output"]
+```
+
+Tool definitions for the LLM are **hardcoded** in `rollout.py` (no introspection endpoint). Mirror the request schemas from `server.py` exactly.
+
+### 4. Dockerfile
+
+Multi-stage build. NeMo Gym pulls Ray and a fairly heavy stack — the Docker image is ~1.5GB. The container exposes port 11000 by default. For HF Spaces deployment, override to port 7860 (one-port limit on Spaces).
+
+## Validation gates
+
+1. **Import** — `uv run python -c "import os; os.environ.setdefault('E2B_API_KEY','x'); from server import MyResourcesServer"` succeeds.
+2. **Local server** — try `uv run python server.py`. **Note**: NeMo Gym's `run_webserver()` initializes a Ray cluster, which fails on shared SLURM / HF cluster nodes (`gcs_server` can't bind). On those machines, only Docker / HF Space deploy works.
+3. **Endpoint smoke** — when running, `curl http://localhost:11000/seed_session -X POST` returns 200 and sets a session cookie.
+4. **Rollout** — `MAX_TURNS=3 uv run python rollout.py` drives end-to-end against the deployed Space.
+
+## Common gotchas
+
+- **`No module named 'anyio'`** — `nemo_gym` doesn't pin its full transitive set on every install. Add `anyio>=4.0`, `attrs>=23.0`, `fastapi>=0.115`, `uvicorn`, `requests` to your `dependencies` explicitly.
+- **`Address already in use` or `gcs_server` crash** — Ray init failed. Almost always a shared cluster issue. Document this and tell the user to deploy via Space.
+- **Cookie not set on the rollout** — make sure to use `requests.Session()`, not raw `requests.post()`. The session cookie is the SID handle.
+- **`/verify` returns reward 0 unexpectedly** — `ground_truth` is wrapped in a list. Check `body.ground_truth[0].get("expected_output")` not `body.ground_truth.get(...)`.
+- **Hardcoded tool schemas drift** — when you change a server endpoint's Pydantic body, manually update the matching tool definition in `rollout.py`. There's no `list_tools()`.
+
+## Reference
+
+- `references/architecture.md` — Ray orchestration, dataset format with `responses_create_params`, deployment notes
+
+## Official documentation
+
+- [NVIDIA-NeMo/Gym](https://github.com/NVIDIA-NeMo/Gym) — source repo
+- [NeMo Gym latest docs](https://docs.nvidia.com/nemo/gym/latest/)
+- [Creating a Resource Server tutorial](https://docs.nvidia.com/nemo/gym/latest/tutorials/creating-resource-server.html)
+- [Creating a Training Environment tutorial](https://docs.nvidia.com/nemo/gym/latest/environment-tutorials/creating-training-environment.html)

package/skills/rl-env/generate-nemo-gym-env/references/architecture.md

@@ -0,0 +1,114 @@
+# NeMo Gym architecture (deep)
+
+## What NeMo Gym is
+
+NVIDIA's RL gym layer for LLM agents. Built on Ray for orchestration. The Python package is `nemo_gym` (install via `pip install git+https://github.com/NVIDIA-NeMo/Gym`). It targets NVIDIA's NeMo training stack but works with TRL/GRPO via raw HTTP.
+
+## Wire protocol
+
+| Method | Path | Purpose |
+|---|---|---|
+| `POST` | `/seed_session` | Initialize a session (sets cookie) |
+| `POST` | `/<tool>` | Each tool registered in `setup_webserver()` |
+| `POST` | `/verify` | Post-episode reward grading |
+
+The session cookie (set on `/seed_session`, named via `SESSION_ID_KEY`) is the only way to associate subsequent tool calls with state. **There is no SDK client** — rollouts speak raw HTTP.
+
+## `SimpleResourcesServer` lifecycle
+
+1. **`MyResourcesServer.run_webserver()`** at `__main__` — boots Ray, starts FastAPI, registers tools.
+2. **`setup_webserver(self)`** — must call `super().setup_webserver()` first to get the `FastAPI` instance with `/seed_session` and `/verify` already registered, then `app.post("/tool")(self.tool)` for each tool.
+3. **`seed_session(self, body)`** — called once per session by `POST /seed_session`. Return `BaseSeedSessionResponse()`. Lazy-init resources here or in the first tool call (recommended).
+4. **Tool methods** — async, take `(self, body, request)`, return a Pydantic response. Read session id via `request.session[SESSION_ID_KEY]`.
+5. **`verify(self, body)`** — async, called once per episode by the trainer. Return `BaseVerifyResponse(**body.model_dump(), reward=...)`. **Always spread the body back** — drops fields silently if you don't.
+
+## Session state pattern
+
+```python
+sessions: Dict[str, Dict[str, Any]] = Field(default_factory=dict)
+
+def _sess(self, request: Request) -> Dict[str, Any]:
+    sid = request.session[SESSION_ID_KEY]
+    if sid not in self.sessions:
+        self.sessions[sid] = {"game": MyGame(), "step": 0}
+    return self.sessions[sid]
+```
+
+Session entries persist for the server's lifetime by default. For long-running deployments, either prune on `verify` or add a TTL.
+
+## Dataset format
+
+NeMo Gym expects datasets with two key fields:
+
+- **`responses_create_params`** — a JSON-stringified OpenAI-Responses-API config (model, tools, system prompt). The trainer feeds this to the model.
+- **`ground_truth`** — a list of dicts (typically one) carrying expected outputs / answer keys. `verify()` reads from this.
+
+Example row:
+```python
+{
+    "responses_create_params": json.dumps({
+        "model": "gpt-4o-mini",
+        "input": [{"role": "user", "content": "Solve 2+2"}],
+        "tools": [{"type": "function", "function": {"name": "guess", ...}}],
+    }),
+    "ground_truth": [{"expected_output": "4"}],
+    "metadata": json.dumps({"task_id": "math-001"}),
+}
+```
+
+## Reward computation in `/verify`
+
+`body.response.output` is a list of items emitted by the model:
+
+| Item type | Field |
+|---|---|
+| `function_call` | `name`, `arguments` (JSON string) |
+| `function_call_output` | `output` (the env's response to that call) |
+| `message` | `content` (list of `output_text` etc.) |
+
+Typical patterns:
+
+**Substring match** — pass if expected appears anywhere:
+```python
+expected = body.ground_truth[0].get("expected_output", "")
+reward = 0.0
+for item in body.response.output:
+    if hasattr(item, "type") and item.type == "function_call_output":
+        if expected.strip() in str(getattr(item, "output", "")).strip():
+            reward = 1.0; break
+```
+
+**Function-call match** — pass if a specific tool was called with success:
+```python
+for item in body.response.output:
+    if getattr(item, "type", "") == "function_call" and item.name == "terminate":
+        args = item.arguments or ""
+        if "success" in args:
+            reward = 1.0; break
+```
+
+## Production deployment
+
+`Dockerfile` is multi-stage; the runtime image is ~1.5GB because of Ray. Healthcheck via `/seed_session`. For HF Spaces:
+
+- Port 7860 (one-port limit on Spaces)
+- Set `app_port: 7860` in README frontmatter
+- HF Spaces handle Ray init reliably (unlike shared SLURM nodes)
+
+## Why `run_webserver()` fails on shared cluster nodes
+
+NeMo Gym's `run_webserver()` calls `ray.init()`, which spawns a `gcs_server` process bound to specific ports. On shared SLURM / HF cluster nodes those ports are already taken, and the bind fails. The error looks like:
+
+```
+[gcs_server] Failed to bind on address ...
+```
+
+There's no fix from the env author's side — deploy via Docker / Space and connect over network.
+
+## What can go wrong
+
+- **Cookie isn't set on the client** — use `requests.Session()`, not naked `requests.post()`.
+- **`gcs_server` crash** — Ray init failure on shared nodes; redirect to deployed Space.
+- **`No module named 'anyio'` / `attrs`** — NeMo Gym's transitive deps drift. Pin them explicitly.
+- **Reward always 0 in verify** — `ground_truth` is a `list`, not a dict. Use `body.ground_truth[0].get(...)`.
+- **`request.session[SESSION_ID_KEY]` raises KeyError** — `/seed_session` wasn't called first; fail fast with a clear error.

package/skills/rl-env/generate-openenv-env/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: generate-openenv-env
+description: Builds an OpenEnv (Hugging Face) variant of an RL environment. Use whenever someone asks to scaffold an OpenEnv server, port an existing env to OpenEnv, add MCP tools to an env, or deploy an OpenEnv to HF Spaces. OpenEnv is the right framework when the user wants HTTP+MCP, structured tool calls discovered via `list_tools()`, an optional Gradio UI, sandbox-backed sessions, or deployment as a Docker container / HF Space. Output is a runnable `<env_dir>/openenv/` folder with `server/app.py`, `server/<env>_environment.py`, `pyproject.toml`, `Dockerfile`, and `rollout.py`. Use for prompts like "wrap my game in OpenEnv", "make an MCP env for X", or "add the openenv variant".
+---
+
+# generate-openenv-env
+
+Build the OpenEnv variant of an env. Targets OpenEnv >= 0.4.1 (the `openenv` package — formerly `openenv-core[core]`).
+
+## Concept
+
+OpenEnv is an HTTP server exposing tools via the **MCP** (Model Context Protocol) shape. The runtime is FastAPI; tools are FastMCP-decorated functions. Clients discover tools via `list_tools()` (under the hood: a list-tools action on `/step`) and call them via `call_tool(name, **args)`.
+
+When the user has a shared domain module (`<domain>.py`) and wants an OpenEnv variant, **never duplicate domain logic into the framework folder** — wrap it.
+
+## Archetypes (pick the one matching the task)
+
+| Archetype | Hallmarks |
+|---|---|
+| **Pure-Python game** | Deterministic, single `@mcp.tool`, text-only observations. Reward computed externally from the trajectory. |
+| **Stateful sandbox** | E2B / browser / DB, multiple tools mutating session state, MCPEnvironment per session. |
+| **Vision / computer-use** | Screenshots returned as MCP image content blocks (`fastmcp.utilities.types.Image`), 19-tool action surface modelled on Anthropic's `computer_20251124`, optional custom Gradio UI mounted at `/web`. |
+
+## Recommended file layout
+
+The user picks the actual paths. The canonical shape:
+
+```
+<env_dir>/openenv/
+├── pyproject.toml      # openenv + e2b-* + fastmcp + uvicorn + gradio
+├── __init__.py
+├── models.py           # Pydantic State / typed action / observation models
+├── Dockerfile          # multi-stage from ghcr.io/huggingface/openenv-base
+├── openenv.yaml        # spec_version 1, name, runtime, app, port
+├── server/
+│   ├── __init__.py
+│   ├── app.py          # create_app(EnvCls, CallToolAction, CallToolObservation, env_name=...)
+│   └── <env>_environment.py    # MCPEnvironment subclass with @mcp.tool methods
+├── rollout.py          # MCPToolClient drives the server; auto-discovers tools
+└── README.md           # one-page; with HF frontmatter if deploying to Spaces
+```
+
+## Implementation order (one continuous pass)
+
+### 1. Pydantic state model — `models.py`
+
+Subclass `openenv.core.env_server.types.State`. Add per-episode fields you'll mutate (`step_count`, `last_output`, sandbox/session ids, anything you want to inspect later).
+
+For visual envs, add `last_screenshot_b64`. Don't store huge blobs unless you need them in `state` — use `metadata` on observations instead.
+
+### 2. The MCPEnvironment — `server/<name>_environment.py`
+
+```python
+class MyEnv(MCPEnvironment):
+    SUPPORTS_CONCURRENT_SESSIONS = True   # only if real session isolation
+    def __init__(self):
+        # ... env-side state init
+        mcp = FastMCP("my_env")
+        @mcp.tool
+        def my_tool(arg: int) -> str: ...
+        super().__init__(mcp)
+```
+
+Key contracts:
+- **Dual-import pattern.** Inside `server/`, write `try: from ..models import X; except ImportError: from models import X`. Relative imports work inside the repo (`PYTHONPATH=src:envs`); flat imports work in Docker (`/app/env`). Same applies to sibling modules like `e2b_sandbox.py`.
+- **Tool methods** are `@mcp.tool` decorated functions inside `__init__`. They close over `self` and read/write env state. Don't try to put `@mcp.tool` on instance methods — FastMCP introspects free functions.
+- **For images**, use `fastmcp.utilities.types.Image`: `return Image(data=png_bytes, format="png")`. The model receives an MCP image content block. Returning a base64 string in text means the model is blind.
+- **Lifecycle hooks**: `reset(seed=None, episode_id=None, **kwargs)` returns an `Observation`; `step(action, timeout_s=None, **kwargs)` is inherited from `MCPEnvironment` for tool dispatch — only override if you need pre/post hooks (e.g. step-counter increment, terminate signal handling).
+
+### 3. The FastAPI app — `server/app.py`
+
+```python
+import os
+from openenv.core.env_server.http_server import create_app
+from openenv.core.env_server.mcp_types import CallToolAction, CallToolObservation
+try:
+    from .my_environment import MyEnv
+    from .gradio_ui import my_ui_builder      # only if you have a custom UI
+except ImportError:
+    from server.my_environment import MyEnv
+    from server.gradio_ui import my_ui_builder
+
+def _custom_gradio_builder(*args, **kwargs):
+    return my_ui_builder(env_factory=MyEnv)
+
+os.environ["ENABLE_WEB_INTERFACE"] = "true"
+app = create_app(
+    MyEnv, CallToolAction, CallToolObservation,
+    env_name="my_env",
+    max_concurrent_envs=int(os.getenv("MAX_CONCURRENT_ENVS", "4")),
+    gradio_builder=_custom_gradio_builder,   # omit if no custom UI
+)
+```
+
+Pass the **class** to `create_app`, not an instantiated env.
+
+### 4. Custom Gradio UI (optional, computer-use-style envs benefit)
+
+`server/gradio_ui.py` defines `my_ui_builder(env_factory)` that returns a `gr.Blocks`. Mounted at `/web` (set `base_path: /web` in the HF Space frontmatter). For computer-use envs, the canonical pattern includes an iframe panel showing the E2B stream URL alongside text controls — but any `gr.Blocks` layout works.
+
+### 5. The rollout — `rollout.py`
+
+Use `openenv.core.mcp_client.MCPToolClient`. **Discover** tools, don't hardcode:
+
+```python
+from openenv.core.mcp_client import MCPToolClient
+with MCPToolClient(base_url=ENV_URL).sync() as env:
+    env.reset()
+    tools = env.list_tools()                 # list of ToolSpec
+    # convert to OpenAI tool schemas, drive the LLM, call env.call_tool(name, **args)
+```
+
+Note: for **image-returning tools**, `env.call_tool` strips to `result.data` (which is `None` for image returns). Use `env.step(CallToolAction(tool_name="screenshot", arguments={}))` to get the full result dict, then read `obs.result["content"][0]["data"]` for the b64 image. Pattern:
+
+```python
+def _call(env, name, **kwargs):
+    out = env.step(CallToolAction(tool_name=name, arguments=kwargs))
+    return out.observation.result or {}
+
+def _b64_screenshot(env):
+    res = _call(env, "screenshot")
+    for c in res.get("content", []) or []:
+        if c.get("type") == "image" and c.get("data"):
+            return c["data"]
+    raise RuntimeError(f"screenshot returned no image: {res}")
+```
+
+For multimodal models (Qwen3-VL, GPT-4o), feed the latest screenshot as an image block in the user message every turn.
+
+### 6. The Dockerfile
+
+Use a multi-stage build:
+- `FROM ghcr.io/huggingface/openenv-base:latest` (the official base — already has FastAPI, MCP, Gradio).
+- `uv sync` twice (no-install-project, then with project) for cache friendliness.
+- Healthcheck via `/health`.
+- Expose port 8000.
+
+For HF Spaces, the canonical `app_port` is **8000** (not 7860 — OpenEnv's pattern uses 8000). Set `base_path: /web` in the README frontmatter so Gradio mounts under that prefix.
+
+### 7. The HF Space README frontmatter
+
+```yaml
+---
+title: My Env Server
+emoji: 🤖
+colorFrom: blue
+colorTo: purple
+sdk: docker
+pinned: false
+app_port: 8000
+base_path: /web
+tags: [openenv, your-domain]
+short_description: One-line summary
+---
+```
+
+## Validation gates
+
+Before declaring done, all four must pass:
+
+1. **In-repo import** — `PYTHONPATH=envs uv run python -c "from envs.<name>.openenv.server.<name>_environment import <Cls>"`
+2. **Local server** — `uv run uvicorn server.app:app --port 8000` then `curl /health` returns `{"status":"healthy"}` and `/list_environments` returns the env name.
+3. **Tool discovery** — `MCPToolClient.list_tools()` returns the expected list.
+4. **Rollout** — `MAX_TURNS=3 uv run python rollout.py` runs without errors.
+
+## Common gotchas (from real-world OpenEnv work)
+
+- **`KeyError: 'tools'` from POST /list_tools** — OpenEnv doesn't expose `/list_tools` directly; `MCPToolClient` uses `/step` with a list-tools action under the hood. Always discover via the client.
+- **Screenshot returns `None`** — `env.call_tool("screenshot")` returns only the structured `data` field. Use `env.step(CallToolAction(...))` and read `obs.result["content"]`.
+- **`address already in use`** — common during local-dev iteration. Just pick a different `--port`.
+- **`ModuleNotFoundError` in Docker but works locally** — missing dual-import pattern in `server/app.py` or `server/<name>_environment.py`.
+
+## Reference
+
+- `references/architecture.md` — full architecture deep-dive (when needed)
+
+## Official documentation
+
+- [huggingface/OpenEnv](https://github.com/huggingface/OpenEnv) — source repo
+- [OpenEnv docs](https://huggingface.co/docs/openenv) — environment-builder + Core API
+- [Build your first environment](https://huggingface.co/docs/openenv/guides/first-environment)
+- [HF org](https://huggingface.co/openenv) — example deployments
+- Upstream ships a `generate-openenv-env` skill at `.claude/skills/generate-openenv-env/` in their repo — useful as a second opinion if behaviour is unclear.

package/skills/rl-env/generate-openenv-env/references/architecture.md

@@ -0,0 +1,82 @@
+# OpenEnv architecture (deep)
+
+## Wire protocol
+
+OpenEnv uses MCP over HTTP. The server exposes:
+
+- `GET  /health` → `{"status": "healthy"}`
+- `GET  /metadata` → env name + description
+- `GET  /openapi.json` → full OpenAPI schema
+- `POST /reset` → start a new episode (body matches `reset()`'s kwargs)
+- `POST /step` → execute an `Action` (`CallToolAction` for tool calls)
+- `GET  /state` → fetch the current `State` object
+- `GET  /web/...` → optional Gradio UI mount (when `ENABLE_WEB_INTERFACE=true`)
+
+The MCP-specific surface lives behind `/step`: a `CallToolAction(tool_name="x", arguments={...})` returns a `CallToolObservation(result={"content": [...], "data": ..., "is_error": ...})`. Tool discovery is via a **list-tools action**, not a separate REST endpoint — `MCPToolClient.list_tools()` does this transparently.
+
+## `MCPEnvironment` lifecycle
+
+1. **`__init__`** — register tools on a `FastMCP` instance, then `super().__init__(mcp)`. Don't allocate per-episode state here; it'll outlive episodes.
+2. **`reset(seed, episode_id, **kwargs)`** — called once per episode. Allocate the sandbox, store session ids in `self._state`, return an `Observation(done=False, reward=None, metadata={...})`.
+3. **`step(action, timeout_s, **kwargs)`** — inherited; dispatches `CallToolAction` to the right `@mcp.tool` function. Override only if you need pre/post hooks (step counter, terminate detection).
+4. **`step_async(...)`** — same but async. If you override `step`, override this too.
+5. **`_step_impl(action, ...)`** — fallback for non-MCP `Action` types. Usually return an error observation.
+6. **`state` property** — returns the current state for `/state` endpoint.
+
+## Concurrent sessions
+
+`SUPPORTS_CONCURRENT_SESSIONS = True` enables the framework to multiplex sessions inside one process. **Only set this if you actually isolate state per session-id** — otherwise sessions clobber each other.
+
+For sandbox-per-episode envs: usually *don't* set this true. Run multiple replicas of the env instead (set `max_concurrent_envs` in `create_app`).
+
+## Tool returns
+
+FastMCP serializes tool returns by inspecting the type:
+
+| Return type | Becomes | Model sees |
+|---|---|---|
+| `str` | `TextContent(type="text", text=...)` | the string |
+| `Image(data=bytes, format="png")` | `ImageContent(type="image", data=<base64>, mimeType="image/png")` | the actual pixels |
+| `dict` | `TextContent` with JSON-serialized `text` | the JSON string |
+| Pydantic model | structured `data` field | depends on client |
+
+For computer-use / vision envs, **always** use `Image`. Returning base64 in a string makes the model effectively blind.
+
+## Custom Gradio UI
+
+Pass `gradio_builder=` to `create_app`. The signature is:
+
+```python
+def builder(web_manager, action_fields, metadata, is_chat_env, title, quick_start_md) -> gr.Blocks: ...
+```
+
+You can ignore most args and just instantiate the env yourself inside the builder. For computer-use envs, the canonical pattern includes an iframe panel showing the E2B sandbox stream URL alongside text controls.
+
+## Dual-import idiom
+
+Inside `server/`, files use:
+
+```python
+try:
+    from .models import State          # works in repo (PYTHONPATH=src:envs)
+except ImportError:
+    from models import State           # works in Docker (PYTHONPATH=/app/env)
+```
+
+Same applies inside `server/<env>_environment.py` for sibling modules. **Always include both.** OpenEnv's CLI builds Docker images that flatten the package layout; the relative import will fail there.
+
+## Production deployment
+
+`Dockerfile` uses `ghcr.io/huggingface/openenv-base:latest` as a multi-stage builder. The runtime image copies the venv and source. Healthcheck via `/health`. For HF Spaces:
+
+- `app_port: 8000` in README frontmatter
+- `base_path: /web` if you want the Gradio UI mounted
+- `E2B_API_KEY` (and any other secrets) as Space secrets, not env vars
+- `MAX_CONCURRENT_ENVS=2` typically — sandbox-per-episode is RAM-heavy
+
+## What can go wrong
+
+- `KeyError: 'tools'` from `POST /list_tools` — that endpoint doesn't exist. Use `MCPToolClient`.
+- Screenshot returns `None` from `env.call_tool("screenshot")` — the convenience method strips to structured `data`. Use `env.step(CallToolAction(...))` and read `obs.result["content"]`.
+- `from ..module import X` fails in Docker — missing dual-import.
+- `ENABLE_WEB_INTERFACE=true` set but no `gradio_builder` passed — Gradio mounts a default UI; set `os.environ["ENABLE_WEB_INTERFACE"]` before `create_app` if you want the custom one.