Docs refresh after 0.7.0 #1296

OpenEnv has grown a lot in the last few releases: Harbor, typed training captures (TrainingTrace), RFC 005 harnesses, production mode, new runtime providers and many new environments. The docs grew with it, and some pages haven't caught up yet. This issue tracks a pass over the README, guides, tutorials and environment READMEs to bring them in line with 0.7.0, so new users find the current way of doing things first.

PRs can reference this issue and tick items as they land. Each group is meant to fit in one PR, but splitting further is fine.

1. Align snippets and commands with the current API

Done in #1297.

• README.md: echo example reads observation.metadata["message"]; CLI list matches the implemented commands (openenv serve isn't available yet, openenv harbor, collect, skills, catalog, discover are); test path in the Contributing section; runtime providers point to the providers guide.
• getting_started/environment-builder.md: install command (pip install openenv or git+https://...), openenv push flags (--tag and --directory aren't options, the directory is positional), Dockerfile in sync with the CLI template (or link it), generated file names (<name>_environment.py, from <name> import ...).
• getting_started/contributing-envs.md: example Space ids (openenv/echo_env, openenv/coding_env, openenv/wordle), openenv.yaml.
• contributing.md: dev setup matches CONTRIBUTING.md (uv sync, PYTHONPATH=src:envs uv run pytest).
• cli/templates/openenv_env/README.md: openenv push flags, sync/async client usage.
• guides/concepts.md and guides/auto-discovery.md: openenv.yaml example matches the CLI template; one client per execution mode (async or .sync()); environment layout tree; AutoAction.from_hub example; package names in install commands.
• guides/task-api.md: client base URL helper (base_url).
• guides/mcp-environment-lifecycle.md: MCPToolClient talks to /mcp, so list_tools()/call_tool() don't go through step() or rewards; step(CallToolAction) is the path for training. Mention the 30 s default tool timeout and timeout_s.
• guides/runtime-providers.md: echo example fields; mark Kubernetes as planned outside the providers table.
• guides/customizing-web-ui.md: custom_tab_name, custom_tab_primary, show_default_tab, title_override; the UI mounts with ENABLE_WEB_INTERFACE=true; current Gradio docs link.
• Tutorials: mcp-environment.md torchforge link; sft-warmup.md format-compliance sentence matches its table; end-to-end-walkthrough.md drift explanation matches GRPO's default beta=0.0; wordle-grpo.md uses dtype=; openenv-tutorial.md anchor and TOC labels.
• Environment READMEs: client examples read fields from result.observation (finqa, connect4, kernrl); websearch uses its client class WebSearchEnv; finqa example query lists columns; browsergym image ghcr.io/huggingface/openenv-browsergym-env; snake/wildfire paths (envs/...); openapp/finrl client class names.

2. Training entry points

• guides/rl-integration.md becomes the Training overview, first in Learn > Training: the ways to train on OpenEnv (white-box tool loop, black-box through Harbor and TrainingTrace, SFT data with openenv collect), each with the frameworks that support it, plus the integrations from the README (TRL, torchforge, Unsloth, SkyRL, ART, Oumi, Lightning AI, Miles). TRL is the most documented integration, not the only one. Drops the "torchforge and SkyRL planned" note. Links the Harnesses overview. (Docs: framework-neutral Training overview and harness pages #1350, which also renames the page to guides/training.md with a redirect from the old URL)
• README.md, docs/source/index.md, getting-started.md: a "Train an agent" step pointing to the TRL tutorial and to Harbor; novita and harbor in the extras table. (Rewrite the README, docs index and Getting Started around what OpenEnv offers #1298)
• A Harbor entry under Learn > Harnesses, linked from the tutorials index: a short page that links TRL's harness training guide, examples/async_grpo_harbor, the multi-harness RL guide and the Harbor environment page, rather than a tutorial that duplicates them. (Docs: organize Harnesses by who owns the loop (white-box, black-box, agent in env) #1349)
• environments.md: Harbor in the main grid near the top. (Docs: production mode and HF sign-in guides, Harbor up front, Spaces metadata (#1296) #1348)
• envs/harbor_env/README.md: base_path: /web and tags in the front matter; Quick Start before Prerequisites (TRL links are in Link the TRL example and the multi-harness article from harbor_env #1293). (Docs: reference for harbor/catalog/discover, harness API and HFSandboxProvider, Harbor README (#1296) #1352)
• src/openenv/core/harness/README.md: Harbor as the main TrainingTrace producer, without the native OpenCode notes. (Remove opencode_env and pi_env (for 0.9.0) #1346, in 0.9.0.) (RFC 005's HarnessEnvironment and AgenticHarnessAdapter are listed since Add a recipe that evaluates Claude Code on τ²-bench (RFC 005) #1291.)
• reference/cli.md: openenv harbor, catalog, discover. reference/core.md: AutoEnv/AutoAction, the harness API (HarnessEnvironment, AgenticHarnessAdapter, ResourceSessionFactory, TrainingTrace), InspectAIHarness, HFSandboxProvider. (Docs: reference for harbor/catalog/discover, harness API and HFSandboxProvider, Harbor README (#1296) #1352)
• guides/simulation-vs-production.md: create_app(..., mode="production"), OPENENV_MODE, WS /harness. (Docs: production mode and HF sign-in guides, Harbor up front, Spaces metadata (#1296) #1348)
• guides/runtime-providers.md and getting-started.md: HFSandboxProvider. (Docs: reference for harbor/catalog/discover, harness API and HFSandboxProvider, Harbor README (#1296) #1352 covers runtime-providers.md; getting-started.md lists Hugging Face among the providers in Rewrite the README, docs index and Getting Started around what OpenEnv offers #1298.) (Docs: fold guides, align titles, keep training pages framework-neutral #1371.)
• guides/customizing-web-ui.md: Hugging Face sign-in on Docker Spaces (Gradio needs SYSTEM=spaces, and its OAuth routes live under /web). (Docs: production mode and HF sign-in guides, Harbor up front, Spaces metadata (#1296) #1348)

Framework-neutral framing

OpenEnv is a neutral contract between environments, harnesses and trainers (see GOVERNANCE.md), so the docs should present training paths in framework-agnostic terms and list TRL as one integration among several.

• tutorials/harnesses.md: the white-box column says "the trainer runs the tool loop" (TRL's environment_factory or another framework's loop) instead of TRL alone, and the black-box column says TrainingTrace is framework-neutral, with TRL's AsyncGRPOTrainer as today's consumer. (Docs: framework-neutral Training overview and harness pages #1350)
• README.md, docs/source/index.md, getting-started.md: the "Train an agent" step leads with the paths and the integrations table, with TRL as the worked example. (Rewrite the README, docs index and Getting Started around what OpenEnv offers #1298)
• An integrations page in the docs (or a section of the Training overview), so the README's integrations list has a home in the docs. (Docs: framework-neutral Training overview and harness pages #1350)

3. Tutorials to refresh

• tutorials/rl-training-2048.md: build on TRL's examples/grpo_2048 with environment_factory, so the tutorial trains end to end; current imports and Space URL. (Docs: refresh Getting Started, walkthrough, SFT warm-up and 2048 tutorials (#1296) #1353, which links Unsloth's own 2048 notebook up front)
• tutorials/browsergym-harness.md and examples/browsergym_harness.py: move to the current TRL API (environment_factory, as in TRL's examples/grpo_browsergym); a title that reflects what it covers (white-box BrowserGym rollouts), linking the Harnesses overview from section 4. (Docs: organize Harnesses by who owns the loop (white-box, black-box, agent in env) #1349)
• Sidebar and tutorials index: the 2048 tutorial is no longer the Unsloth one (Docs: refresh Getting Started, walkthrough, SFT warm-up and 2048 tutorials (#1296) #1353), so its "Unsloth" titles change. (Docs: fold guides, align titles, keep training pages framework-neutral #1371.)
• examples/OpenEnv_Tutorial.ipynb: regenerate from openenv-tutorial.md. (Docs: trim the Hello World tutorial and regenerate its notebook #1372.)
• Getting Started notebooks (parts 1-3): connect with base_url="https://openenv-openspiel-env.hf.space". (Docs: refresh Getting Started, walkthrough, SFT warm-up and 2048 tutorials (#1296) #1353)
• tutorials/end-to-end-walkthrough.md: environment-owned reward (get_reward()) and optional dataset; environment pool wording. (Docs: refresh Getting Started, walkthrough, SFT warm-up and 2048 tutorials (#1296) #1353)
• tutorials/sft-warmup.md: one collection API across page and notebook; default loss filtering; current teacher model names. (Docs: refresh Getting Started, walkthrough, SFT warm-up and 2048 tutorials (#1296) #1353)
• tutorials/claude-code-harness.md: open with what it is for (evaluating an agent you don't control with the environment's tools and a simulated user, and when to use Harbor instead), a diagram of the flow (Claude Code, MCP bridge, environment tools, simulated customer, rubric), define pass^1, demo tasks that write to the database, and one line on what production mode is for. The BrowserGym comparison moves to the Harnesses overview. (Docs: organize Harnesses by who owns the loop (white-box, black-box, agent in env) #1349)

4. Structure and length

• Fold guides/mcp-environment-lifecycle.md into guides/simulation-vs-production.md, and keep the combined page short. (Docs: fold guides, align titles, keep training pages framework-neutral #1371.)
• Fold guides/connecting.md into guides/runtime-providers.md. (Docs: fold guides, align titles, keep training pages framework-neutral #1371.)
• guides/catalog-discovery.md: keep usage (build, discover, inspect, discovery.json), move the spec details to RFC 011. Trim guides/auto-discovery.md. (Docs: trim the catalog, auto-discovery and Harbor qualification guides, tighten environment READMEs (#1296) #1370; the 0.1-draft profile spec stays, rewritten, at the end of the guide instead of moving to RFC 011, which is still a draft.)
• One "build an environment" walkthrough across concepts.md, first-environment.md and environment-builder.md. (Docs: one build-an-environment walkthrough #1373.)
• guides/harbor-provider-qualification.md: nav title "Harbor Qualification", next to the Harbor page; keep how qualification works, link the dated matrix. (Docs: production mode and HF sign-in guides, Harbor up front, Spaces metadata (#1296) #1348 does the title and placement; trimming the page is still open.) (Docs: trim the catalog, auto-discovery and Harbor qualification guides, tighten environment READMEs (#1296) #1370; the dated results stay in the guide, collapsed.)
• tutorials/openenv-tutorial.md: shorter, focused on setup, the local server and the environment skeleton. (Docs: trim the Hello World tutorial and regenerate its notebook #1372.)
• README.md: shorter Architecture / Project Structure sections with links to the docs; link rfcs/ instead of listing RFCs. (Rewrite the README, docs index and Getting Started around what OpenEnv offers #1298)
• Shared blocks (governance, experimental note) in one place. (Docs: fold guides, align titles, keep training pages framework-neutral #1371; the committee list lives in the README, the early-development note stays in the README and the docs index.)
• A Harnesses overview page at the top of Learn > Harnesses, organized by who owns the loop: white-box (the trainer runs the tool loop), black-box (a real agent owns its loop and Harbor captures its tokens) and an agent inside the environment (RFC 005, tools injected over MCP, no capture, for evaluation and serving). The Harness runtime replacement #652 session runtime gets a note (it backs openenv collect). It also answers Confusion around RFC 005 #696. (Docs: organize Harnesses by who owns the loop (white-box, black-box, agent in env) #1349)
• _toctree.yml: Core Concepts first; Getting Started pages together; same titles in the sidebar, the tutorials index and page headings. (Docs: fold guides, align titles, keep training pages framework-neutral #1371.)
• Environment READMEs: link the CLI docs instead of repeating the openenv push options (openspiel, maze, reasoning_gym, textarena, websearch); keep README content user-facing (openapp, repl); shorter wildfire and unity; grid_world as an environment README; a client example, tools and reward for calendar; one name for the reward section. (Docs: trim the catalog, auto-discovery and Harbor qualification guides, tighten environment READMEs (#1296) #1370, textarena in Docs: fold guides, align titles, keep training pages framework-neutral #1371.)

5. Spaces and deployment

• scripts/prepare_hf_deployment.sh (create_readme): generated Space cards use the env's client class and its *.hf.space URL. (Docs: Space cards with a working client snippet, CARLA example URL (#1296) #1351, the snippet only for public Spaces)
• Redeploy the openenv org Spaces on a current release. (Done on v0.10.0, plus new snake, dipg, grid_world, chess, carla and terminus Spaces, see the comment below.) (After the next 0.8.x release, since Fix OpenEnv ref pinned by prepare_hf_deployment.sh #1366 and Default HF deploy workflow to the latest stable release tag #1376 pin the latest stable tag. openenv/echo_env was redeployed from v0.8.0 but is paused by a Hub flag that the Spaces team has to clear.)
• Front matter for chess, dipg_safety, finrl, git, kernrl, sumo_rl; named colors for atari and chat. (Docs: production mode and HF sign-in guides, Harbor up front, Spaces metadata (#1296) #1348)
• openenv push: works without models.py (openenv push: don't require models.py (MCP envs like echo_env) #1356) and removes files from earlier pushes that the environment no longer ships (openenv push: remove stale Space files and skip build artifacts #1365).
• openenv push keeps files added by hand on the Space and files matching --exclude or the default ignores, and lists each deletion. (Keep user-added and excluded files when pushing to a Space #1377)
• prepare_hf_deployment.sh pins the latest vX.Y.Z tag by default instead of a stale version. (Fix OpenEnv ref pinned by prepare_hf_deployment.sh #1366)
• The HF deploy workflow uses that default and fetches tags, and pre-release tags are skipped. (Default HF deploy workflow to the latest stable release tag #1376)
• openenv init template: server --port works, the printed next steps and the image tag match what openenv build produces. (Fix openenv init template: server --port, next steps and image tags #1374)
• environments.md buttons point to running Spaces (snake, dipg, grid_world, browsergym → openenv/browsergym_env); carla and chess Space links. (The snake, dipg, grid_world, carla and RLVE_Gym Spaces are in a runtime or build error and have no openenv/ copy, so their buttons wait for a redeploy.)
• Link the existing openenv/* Spaces from their READMEs (echo, coding, textarena, repl, tbench2, sumo, terminus). (Docs: production mode and HF sign-in guides, Harbor up front, Spaces metadata (#1296) #1348 links echo, coding and textarena. tbench2, sumo and terminus can't wake up while the openenv organization is over its quota, and openenv/repl is in a runtime error, so they wait for the redeploy above.)
• openenv/wordle Space: depend on current openenv. (On v0.10.0, and the rewritten tutorial in Train a Wordle agent: SFT, then GRPO #1479 runs against it.) (It pins openenv-core @ meta-pytorch/OpenEnv@v0.2.3, and the Wordle tutorial installs it with pip install git+https://huggingface.co/spaces/openenv/wordle. Part of the redeploy above, then re-run the tutorial against it.)