Align docs snippets and commands with the current API

README.md

@@ -42,7 +42,7 @@ async def main():
     async with EchoEnv(base_url="https://openenv-echo-env.hf.space") as client:
         # Reset the environment
         result = await client.reset()
-        print(result.observation.echoed_message)  # "Echo environment ready!"
+        print(result.observation.metadata["message"])  # "Echo environment ready!"
 
         # Send messages
         result = await client.step(
@@ -174,9 +174,8 @@ Base class for environment communication:
 #### 4. Container Providers
 Manage container deployment:
 - `LocalDockerProvider`: Run containers on local Docker daemon
-- `DockerSwarmProvider`: Deploy to Docker Swarm clusters
-- `UVProvider`, `DaytonaProvider`, `ACASandboxProvider`: Additional runtime providers
-- `KubernetesProvider`: Deploy to Kubernetes clusters (planned)
+- `UVProvider`: Run an environment's server from its project directory, without Docker
+- Docker Swarm, Daytona, Modal, Novita, Azure Container Apps and Hugging Face sandboxes: see [Runtime Providers](https://huggingface.co/docs/openenv/guides/runtime-providers)
 
 #### 5. Models
 Type-safe data structures:
@@ -270,10 +269,13 @@ The OpenEnv CLI provides commands to manage environments:
 - **`openenv init <env_name>`** - Initialize a new environment from template
 - **`openenv import <source> --name <env_name> --output-dir <dir>`** - Wrap a supported third-party source environment, including ORS/OpenReward and Verifiers, as OpenEnv
 - **`openenv push [--repo-id <repo>] [--private]`** - Deploy environment to Hugging Face Spaces
-- **`openenv serve`** - Serve an environment locally with optional auto-reload
 - **`openenv build`** - Build the Docker image for an environment
 - **`openenv fork <space-id>`** - Fork a Space from HF Hub to your account
 - **`openenv validate`** - Validate an environment configuration
+- **`openenv harbor`** - Serve and run Harbor tasks with token-level capture (`info`, `rollout`, `serve`, `push`)
+- **`openenv collect`** - Collect rollouts from a deployed environment
+- **`openenv catalog`** / **`openenv discover`** - Build and search environment catalogs
+- **`openenv skills`** - Manage OpenEnv skills for AI assistants
 
 ### Quick Start
 
@@ -318,7 +320,7 @@ uv pip install pytest
 PYTHONPATH=src:envs uv run pytest tests/ -v --tb=short
 
 # Run a specific test file
-PYTHONPATH=src:envs uv run pytest tests/envs/test_echo_environment.py -v
+PYTHONPATH=src:envs uv run pytest tests/envs/test_chess_environment.py -v
 ```
 
 **To run environment-specific tests**, install that environment's dependencies:

docs/source/contributing.md

@@ -53,7 +53,7 @@ Documentation improvements are always welcome:
 1. Fork the repository
 2. Create a feature branch: `git checkout -b feature/my-feature`
 3. Make your changes
-4. Run tests: `pytest`
+4. Run tests: `PYTHONPATH=src:envs uv run pytest tests/`
 5. Submit a pull request
 
 ## Development Setup
@@ -63,14 +63,15 @@ Documentation improvements are always welcome:
 git clone https://github.com/YOUR_USERNAME/OpenEnv.git
 cd OpenEnv
 
-# Install in development mode
-pip install -e ".[dev]"
+# Install in development mode, with the dev tools
+uv sync
 
 # Run tests
-pytest
+PYTHONPATH=src:envs uv run pytest tests/
 
 # Run linting
-ruff check .
+uv run ruff check src/ tests/
+uv run ruff format --check src/ tests/
 ```
 
 ## Code Style

docs/source/environments/browsergym.md

@@ -32,7 +32,7 @@ from browsergym_env import BrowserGymEnv, BrowserGymAction
 
 # Create environment for MiniWoB training task
 env = BrowserGymEnv.from_docker_image(
-    "ghcr.io/openenv/browsergym-env:latest",
+    "ghcr.io/huggingface/openenv-browsergym-env:latest",
     environment={
         "BROWSERGYM_BENCHMARK": "miniwob",
         "BROWSERGYM_TASK_NAME": "click-test",  # or "click-button", "click-dialog", etc.
@@ -261,7 +261,7 @@ from envs.browsergym_env import BrowserGymEnv, BrowserGymAction
 
 # Create environment for WebArena evaluation
 env = BrowserGymEnv.from_docker_image(
-    "ghcr.io/openenv/browsergym-env:latest",
+    "ghcr.io/huggingface/openenv-browsergym-env:latest",
     environment={
         "BROWSERGYM_BENCHMARK": "webarena",
         "BROWSERGYM_TASK_NAME": "0",  # Task ID
@@ -560,7 +560,7 @@ python app.py
 browsergym_env/
 ├── __init__.py              # Module exports
 ├── models.py                # Action, Observation, State dataclasses
-├── client.py                # HTTPEnvClient implementation
+├── client.py                # BrowserGymEnv client (EnvClient)
 ├── README.md                # This file
 └── server/
     ├── __init__.py

docs/source/environments/connect4.md

@@ -11,9 +11,9 @@ from connect4_env import Connect4Action, Connect4Env
 
 async def main():
     async with Connect4Env(base_url="http://localhost:8000") as client:
-        obs = await client.reset()
-        print(f"Board: {obs.board}")
-        print(f"Legal moves: {obs.legal_actions}")
+        result = await client.reset()
+        print(f"Board: {result.observation.board}")
+        print(f"Legal moves: {result.observation.legal_actions}")
 
         # Drop a piece in column 3
         result = await client.step(Connect4Action(column=3))

docs/source/environments/finqa.md

@@ -56,9 +56,9 @@ from envs.finqa_env import FinQAEnv, CallToolAction
 async def main():
     async with FinQAEnv(base_url="http://localhost:8000") as env:
         # Reset to get a question
-        obs = await env.reset()
-        question = obs.metadata["question"]
-        company = obs.metadata["company"]
+        result = await env.reset()
+        question = result.observation.metadata["question"]
+        company = result.observation.metadata["company"]
         print(f"Question: {question}")
         print(f"Company: {company}")
 
@@ -76,7 +76,8 @@ async def main():
             arguments={
                 "company_name": "alphabet",
                 "table_name": "us_gaap_ScheduleOfIncomeBeforeIncomeTaxDomesticAndForeignTableTextBlock",
-                "query": "SELECT * FROM data WHERE year = '2022'"
+                # Name the columns you need (see get_table_info); SELECT * is rejected
+                "query": "SELECT <columns> FROM data WHERE year = '2022'"
             }
         ))
         print(f"Done: {step_result.done}, Reward: {step_result.reward}")

docs/source/environments/finrl.md

@@ -122,7 +122,7 @@ client.close()
 │                            │                                 │
 │                   ┌────────▼────────┐                        │
 │                   │ FinRLEnv        │ ← HTTP Client          │
-│                   │ (HTTPEnvClient) │                        │
+│                   │ (EnvClient)     │                        │
 │                   └────────┬────────┘                        │
 └────────────────────────────┼─────────────────────────────────┘
                              │ HTTP (JSON)

docs/source/environments/kernrl.md

@@ -34,8 +34,8 @@ from kernrl import KernelAction, kernrl_env
 env = kernrl_env(base_url="http://localhost:8000")
 
 # Start episode
-obs = env.reset(problem_id="L1_23_Softmax")
-print(obs.problem_description)
+result = env.reset(problem_id="L1_23_Softmax")
+print(result.observation.problem_description)
 
 # Submit a kernel
 action = KernelAction(code='''

docs/source/environments/maze.md

@@ -71,7 +71,7 @@ You can easily deploy your OpenEnv environment to Hugging Face Spaces using the
 openenv push
 
 # Or specify options
-openenv push --namespace my-org --private
+openenv push --repo-id my-org/my-env --private
 ```
 
 The `openenv push` command will:
@@ -85,7 +85,7 @@ The `openenv push` command will:
 
 ### Options
 
-- `--directory`, `-d`: Directory containing the OpenEnv environment (defaults to current directory)
+- `DIRECTORY` (positional): Directory containing the OpenEnv environment (defaults to current directory)
 - `--repo-id`, `-r`: Repository ID in format 'username/repo-name' (defaults to 'username/env-name' from openenv.yaml)
 - `--base-image`, `-b`: Base Docker image to use (overrides Dockerfile FROM)
 - `--private`: Deploy the space as private (default: public)

docs/source/environments/openapp.md

@@ -68,7 +68,7 @@ openapp_env/
 
 **Key Components:**
 
-- **client.py**: `OpenAppEnv` class that extends `HTTPEnvClient` for remote environment interaction
+- **client.py**: `OpenAppEnv` class that extends `EnvClient` for remote environment interaction
 - **models.py**: `OpenAppAction` and `OpenAppObservation` dataclasses with validation
 - **server/openapp_environment.py**: `OpenAppEnvironment` class that wraps BrowserGym and OpenApps
 - **server/app.py**: FastAPI server that exposes the environment via HTTP endpoints

docs/source/environments/openspiel.md

@@ -88,7 +88,7 @@ You can easily deploy your OpenEnv environment to Hugging Face Spaces using the
 openenv push
 
 # Or specify options
-openenv push --namespace my-org --private
+openenv push --repo-id my-org/my-env --private
 ```
 
 The `openenv push` command will:
@@ -102,7 +102,7 @@ The `openenv push` command will:
 
 ### Options
 
-- `--directory`, `-d`: Directory containing the OpenEnv environment (defaults to current directory)
+- `DIRECTORY` (positional): Directory containing the OpenEnv environment (defaults to current directory)
 - `--repo-id`, `-r`: Repository ID in format 'username/repo-name' (defaults to 'username/env-name' from openenv.yaml)
 - `--base-image`, `-b`: Base Docker image to use (overrides Dockerfile FROM)
 - `--private`: Deploy the space as private (default: public)

docs/source/environments/reasoning_gym.md

@@ -71,7 +71,7 @@ You can easily deploy your OpenEnv environment to Hugging Face Spaces using the
 openenv push
 
 # Or specify options
-openenv push --namespace my-org --private
+openenv push --repo-id my-org/my-env --private
 ```
 
 The `openenv push` command will:
@@ -86,7 +86,7 @@ The `openenv push` command will:
 
 ### Options
 
-- `--directory`, `-d`: Directory containing the OpenEnv environment (defaults to current directory)
+- `DIRECTORY` (positional): Directory containing the OpenEnv environment (defaults to current directory)
 - `--repo-id`, `-r`: Repository ID in format 'username/repo-name' (defaults to 'username/env-name' from openenv.yaml)
 - `--base-image`, `-b`: Base Docker image to use (overrides Dockerfile FROM)
 - `--private`: Deploy the space as private (default: public)

docs/source/environments/snake.md

@@ -60,7 +60,7 @@ client.close()
 
 ```bash
 # Install dependencies
-cd src/envs/snake_env
+cd envs/snake_env
 pip install -e .
 
 # Run server
@@ -240,7 +240,7 @@ pip install git+https://github.com/kc-ml2/marlenv.git
 Make sure you're in the correct directory when running the server:
 
 ```bash
-cd src/envs/snake_env
+cd envs/snake_env
 uv run --project . server
 ```
 

docs/source/environments/textarena.md

@@ -98,7 +98,7 @@ You can easily deploy your OpenEnv environment to Hugging Face Spaces using the
 openenv push
 
 # Or specify options
-openenv push --namespace my-org --private
+openenv push --repo-id my-org/my-env --private
 ```
 
 The `openenv push` command will:
@@ -112,7 +112,7 @@ The `openenv push` command will:
 
 ### Options
 
-- `--directory`, `-d`: Directory containing the OpenEnv environment (defaults to current directory)
+- `DIRECTORY` (positional): Directory containing the OpenEnv environment (defaults to current directory)
 - `--repo-id`, `-r`: Repository ID in format 'username/repo-name' (defaults to 'username/env-name' from openenv.yaml)
 - `--base-image`, `-b`: Base Docker image to use (overrides Dockerfile FROM)
 - `--private`: Deploy the space as private (default: public)

docs/source/environments/websearch.md

@@ -39,15 +39,14 @@ This environment requires a Serper.dev API key to function.
 
 ## Quick Start
 
-The simplest way to use the Web Search environment is through the `WebSearchEnvironment` class:
+The simplest way to use the Web Search environment is through the `WebSearchEnv` client:
 
 ```python
-from envs.websearch_env.server.websearch_env_environment import WebSearchEnvironment
-from envs.websearch_env import WebSearchAction
+from envs.websearch_env import WebSearchAction, WebSearchEnv
 
 try:
     # Create environment from Docker image
-    web_search_env = WebSearchEnvironment.from_docker_image("web_search-env:latest")
+    web_search_env = WebSearchEnv.from_docker_image("web_search-env:latest")
 
     # Reset
     result = web_search_env.reset()
@@ -65,7 +64,7 @@ finally:
     web_search_env.close()
 ```
 
-That's it! The `WebSearchEnvironment.from_docker_image()` method handles:
+That's it! The `WebSearchEnv.from_docker_image()` method handles:
 - Starting the Docker container
 - Waiting for the server to be ready
 - Connecting to the environment
@@ -90,7 +89,7 @@ You can easily deploy your OpenEnv environment to Hugging Face Spaces using the
 openenv push
 
 # Or specify options
-openenv push --namespace my-org --private
+openenv push --repo-id my-org/my-env --private
 ```
 
 The `openenv push` command will:
@@ -104,7 +103,7 @@ The `openenv push` command will:
 
 ### Options
 
-- `--directory`, `-d`: Directory containing the OpenEnv environment (defaults to current directory)
+- `DIRECTORY` (positional): Directory containing the OpenEnv environment (defaults to current directory)
 - `--repo-id`, `-r`: Repository ID in format 'username/repo-name' (defaults to 'username/env-name' from openenv.yaml)
 - `--base-image`, `-b`: Base Docker image to use (overrides Dockerfile FROM)
 - `--private`: Deploy the space as private (default: public)
@@ -164,10 +163,10 @@ The reward is undefined here.
 If you already have a Web Search environment server running, you can connect directly:
 
 ```python
-from envs.websearch_env import WebSearchEnvironment
+from envs.websearch_env import WebSearchAction, WebSearchEnv
 
 # Connect to existing server
-web_search_env = WebSearchEnvironment(base_url="<ENV_HTTP_URL_HERE>")
+web_search_env = WebSearchEnv(base_url="<ENV_HTTP_URL_HERE>")
 
 # Use as normal
 result = web_search_env.reset()

docs/source/environments/wildfire.md

@@ -447,7 +447,7 @@ This approach:
 docker build -t openenv-base:latest -f src/openenv/core/containers/images/Dockerfile .
 
 # Build wildfire environment using the script
-cd src/envs/wildfire_env/server
+cd envs/wildfire_env/server
 ./build_docker.sh
 
 # Run container
@@ -1014,7 +1014,7 @@ docker build -t wildfire-env:latest -f envs/wildfire_env/server/Dockerfile .
 
 - **Main Repository**: [OpenEnv GitHub](https://github.com/openenv)
 - **Documentation**: See `rfcs/` directory for design documents
-- **Other Environments**: See `src/envs/` for more environment examples
+- **Other Environments**: See `envs/` for more environment examples
 
 ### Related Tools
 

docs/source/getting_started/contributing-envs.md

@@ -4,7 +4,7 @@ OpenEnv environments are designed to be shared. The `openenv` CLI provides first
 commands for publishing, forking, and contributing to environments hosted as
 [Hugging Face Spaces](https://huggingface.co/spaces).
 
-Envs are deployed as Hugging Face Spaces which are; Git repositories, Docker images, Python packages, and Gradio apps
+Envs are deployed as Hugging Face Spaces, which are Git repositories, Docker images, Python packages and Gradio apps at once.
 
 This guide covers three workflows:
 
@@ -33,7 +33,7 @@ The `openenv` CLI will also prompt you to log in automatically if you haven't al
 Once you've [built an environment](environment-builder.md), publishing it to a Hugging Face Space is a single command.
 
 ```bash
-# Push the env at '.' to the hub with config in env.yaml
+# Push the env at '.' to the hub with config in openenv.yaml
 openenv push
 
 # Push the env to a specific repo
@@ -61,23 +61,23 @@ Forking creates a copy of a Hugging Face Space under your own account. This is
 the fastest way to start experimenting with an existing environment.
 
 ```bash
-# Fork the openenv/wordle-env environment to your account
+# Fork the openenv/wordle environment to your account
 openenv fork owner/space-name
 ```
 
 This duplicates the Space to `<your-username>/space-name` using the same name and config. To make changes, you can fork to a specific repo name, set environment variables and secrets, and request hardware.
 
 ```bash
 # Fork to a specific repo name
-openenv fork openenv/wordle-env --repo-id my-username/my-wordle
+openenv fork openenv/wordle --repo-id my-username/my-wordle
 
-# Fork the openenv/coding-env environment to your account with environment variables and secrets
-openenv fork openenv/coding-env \
+# Fork the openenv/coding_env environment to your account with environment variables and secrets
+openenv fork openenv/coding_env \
   --set-env MODEL_ID=meta-llama/Llama-3-8B \
   --set-secret HF_TOKEN=hf_xxxxxxxxxxxxx
 
-# Fork the openenv/coding-env environment to your account with a GPU
-openenv fork openenv/coding-env --hardware t4-medium
+# Fork the openenv/coding_env environment to your account with a GPU
+openenv fork openenv/coding_env --hardware t4-medium
 ```
 
 
@@ -167,7 +167,7 @@ submitting a PR.
 
 ```bash
 # Fork the echo environment
-openenv fork openenv/echo-env --repo-id my-username/echo-env-improved
+openenv fork openenv/echo_env --repo-id my-username/echo-env-improved
 
 # Clone your fork
 git clone https://huggingface.co/spaces/my-username/echo-env-improved
@@ -180,7 +180,7 @@ cd echo-env-improved
 openenv validate --level static --skip-build
 
 # Push your improvement as a PR to the original
-openenv push --repo-id openenv/echo-env --create-pr
+openenv push --repo-id openenv/echo_env --create-pr
 ```
 
 ## Next Steps