docs: Environment Builder client uses .sync() handle (from #1129)

.claude/skills/generate-openenv-env/references/openenv-docs-environment-builder.md

@@ -378,12 +378,12 @@ For an end-to-end example of using your environment, see the [Quick Start](quick
 ```python
 from envs.my_env import MyAction, MyEnv
 
-# Create environment from Docker image
-client = MyEnv.from_docker_image("my-env:latest")
-# Or, connect to the remote space on Hugging Face
-client = MyEnv.from_hub("my-org/my-env")
-# Or, connect to the local server
-client = MyEnv(base_url="http://localhost:8000")
+# Create environment from Docker image (starts a container)
+client = MyEnv.from_docker_image("my-env:latest").sync()
+# Or, run the image of a Hugging Face Space locally
+client = MyEnv.from_env("my-org/my-env").sync()
+# Or, connect to an already running server
+client = MyEnv(base_url="http://localhost:8000").sync()
 
 # Use context manager for automatic cleanup (recommended)
 with client:
@@ -403,13 +403,40 @@ with client:
 
 # Or manually manage the connection
 try:
-    client = MyEnv(base_url="http://localhost:8000")
+    client = MyEnv(base_url="http://localhost:8000").sync()
     result = client.reset()
     result = client.step(MyAction(command="test", parameters={}))
 finally:
     client.close()
 ```
 
+`from_docker_image()` and `from_env()` do not return a connected client. They
+return a lazy bootstrap handle, and nothing starts until you resolve it: chain
+`.sync()` for a synchronous client (as above), or `await` the handle from async
+code. Using the handle directly in a `with` block raises
+`TypeError: '_BootstrapResult' object does not support the context manager protocol`.
+
+The equivalent async usage is:
+
+```python
+import asyncio
+
+from envs.my_env import MyAction, MyEnv
+
+
+async def main():
+    client = await MyEnv.from_docker_image("my-env:latest")
+    async with client:
+        result = await client.reset()
+        result = await client.step(MyAction(command="test", parameters={}))
+        state = await client.state()
+
+
+asyncio.run(main())
+```
+
+See [Async vs Sync Usage](../guides/async-sync) for when to prefer each style.
+
 ## Troubleshooting
 
 ### WebSocket Connection Closed During RL Training

docs/source/getting_started/environment-builder.md

@@ -20,7 +20,7 @@ Already familiar with OpenEnv? Here's the 8-step process at a glance:
 | 5 | `uv run --project . server` | Start local dev server for testing |
 | 6 | `openenv validate --level static --skip-build` | Validate the declared manifest contract |
 | 7 | `openenv push` | Deploy to Hugging Face Hub |
-| 8 | Share the URL! | Others use via `MyEnv.from_hub("you/my-env")` |
+| 8 | Share it! | Others use via `MyEnv.from_env("you/my-env").sync()` |
 
 ### CLI Quick Reference
 
@@ -410,12 +410,12 @@ Here is a simple example of using your environment:
 ```python
 from envs.my_env import MyAction, MyEnv
 
-# Create environment from Docker image
-client = MyEnv.from_docker_image("my-env:latest")
-# Or, connect to the remote space on Hugging Face
-client = MyEnv.from_hub("my-org/my-env")
-# Or, connect to the local server
-client = MyEnv(base_url="http://localhost:8000")
+# Create environment from Docker image (starts a container)
+client = MyEnv.from_docker_image("my-env:latest").sync()
+# Or, run the image of a Hugging Face Space locally
+client = MyEnv.from_env("my-org/my-env").sync()
+# Or, connect to an already running server
+client = MyEnv(base_url="http://localhost:8000").sync()
 
 # Use context manager for automatic cleanup (recommended)
 with client:
@@ -435,13 +435,40 @@ with client:
 
 # Or manually manage the connection
 try:
-    client = MyEnv(base_url="http://localhost:8000")
+    client = MyEnv(base_url="http://localhost:8000").sync()
     result = client.reset()
     result = client.step(MyAction(command="test", parameters={}))
 finally:
     client.close()
 ```
 
+`from_docker_image()` and `from_env()` do not return a connected client. They
+return a lazy bootstrap handle, and nothing starts until you resolve it: chain
+`.sync()` for a synchronous client (as above), or `await` the handle from async
+code. Using the handle directly in a `with` block raises
+`TypeError: '_BootstrapResult' object does not support the context manager protocol`.
+
+The equivalent async usage is:
+
+```python
+import asyncio
+
+from envs.my_env import MyAction, MyEnv
+
+
+async def main():
+    client = await MyEnv.from_docker_image("my-env:latest")
+    async with client:
+        result = await client.reset()
+        result = await client.step(MyAction(command="test", parameters={}))
+        state = await client.state()
+
+
+asyncio.run(main())
+```
+
+See [Async vs Sync Usage](../guides/async-sync) for when to prefer each style.
+
 ## Nice work! You've now built and used your own OpenEnv environment.
 
 Your next steps are to:

docs/source/guides/task-api.md

@@ -229,7 +229,7 @@ Note that the Task API is served over HTTP while episodes typically run over the
 From a training or evaluation loop, discovery and episode control then compose naturally:
 
 ```python
-with LatexOCREnv.from_docker_image("latex-ocr-env:latest") as env:
+with LatexOCREnv.from_docker_image("latex-ocr-env:latest").sync() as env:
     total = env.num_tasks("test")
     for index in range(total):
         result = env.reset(split="test", index=index)

tests/test_core/test_generic_client.py

@@ -593,6 +593,69 @@ def test_from_docker_image_stops_container_on_construction_failure(
 
         mock_provider.stop_container.assert_called_once_with()
 
+    _RESET_RESPONSE = (
+        '{"type": "response", "data": {"observation": {"ready": true}, '
+        '"reward": 0.0, "done": false}}'
+    )
+
+    def test_documented_sync_usage_with_block_and_reset(self, mock_provider):
+        """The Environment Builder docs' sync example works end-to-end (issue #1118).
+
+        `client = MyEnv.from_docker_image(...).sync()` followed by
+        `with client: client.reset()` must connect on the sync loop, return a
+        concrete StepResult (not a coroutine), and release the container on exit.
+        """
+        fake_connect, sockets = self._fake_ws_connect()
+
+        with patch("openenv.core.env_client.ws_connect", side_effect=fake_connect):
+            client = GenericEnvClient.from_docker_image(
+                image="my-env:latest",
+                provider=mock_provider,
+            ).sync()
+            sockets[0].recv.return_value = self._RESET_RESPONSE
+
+            with client:
+                result = client.reset()
+
+        if asyncio.iscoroutine(result):
+            result.close()
+            pytest.fail("client.reset() returned a coroutine in synchronous code")
+        assert isinstance(result, StepResult)
+        assert result.observation == {"ready": True}
+        assert result.done is False
+        # `with` on the eagerly connected sync handle must reuse its socket.
+        assert len(sockets) == 1
+        mock_provider.start_container.assert_called_once_with("my-env:latest")
+        mock_provider.stop_container.assert_called_once_with()
+
+    @pytest.mark.asyncio
+    async def test_documented_async_usage_async_with_and_reset(self, mock_provider):
+        """The Environment Builder docs' async example works end-to-end (issue #1118).
+
+        `client = await MyEnv.from_docker_image(...)` followed by
+        `async with client: await client.reset()` must reuse the connection
+        opened by the handle and release the container on exit.
+        """
+        fake_connect, sockets = self._fake_ws_connect()
+
+        with patch("openenv.core.env_client.ws_connect", side_effect=fake_connect):
+            client = await GenericEnvClient.from_docker_image(
+                image="my-env:latest",
+                provider=mock_provider,
+            )
+            assert isinstance(client, GenericEnvClient)
+            sockets[0].recv.return_value = self._RESET_RESPONSE
+
+            async with client:
+                result = await client.reset()
+
+        assert isinstance(result, StepResult)
+        assert result.observation == {"ready": True}
+        # `async with` on an already-connected client must not open a second socket.
+        assert len(sockets) == 1
+        mock_provider.start_container.assert_called_once_with("my-env:latest")
+        mock_provider.stop_container.assert_called_once_with()
+
 
 class TestBaseUrlProperty:
     """Test the public read-only base_url property (issue #935)."""