[sergiopaniego]

Summary

Part of #1296, section 1: snippets and commands in the docs now match the current API, so they work when copied. No behavior changes.

• README.md: echo example reads observation.metadata["message"]; the CLI list matches the implemented commands (adds harbor, collect, catalog/discover, skills, and drops serve, which isn't implemented yet); runtime providers point to the providers guide; test path.
• getting_started/environment-builder.md: pip install openenv; openenv push takes the directory as a positional argument (there is no --directory or --tag on push), plus the options it was missing; links the CLI template's Dockerfile instead of embedding a copy; generated file names (my_env_environment.py, from my_env import ...).
• getting_started/contributing-envs.md: Space ids that exist (openenv/echo_env, openenv/coding_env, openenv/wordle), openenv.yaml.
• contributing.md: dev setup as in CONTRIBUTING.md (uv sync, PYTHONPATH=src:envs uv run pytest, ruff).
• CLI template README and the same block in five environment READMEs (openspiel, maze, reasoning_gym, textarena, websearch): openenv push flags.
• guides/concepts.md, guides/auto-discovery.md: openenv.yaml examples match the CLI template and coding_env's manifest (action:/observation: as class names, which is what discovery reads); one client per execution mode; environment layout; AutoAction.from_hub example; install commands (environment packages come from the repo or their Space).
• guides/task-api.md: the client helper uses base_url.
• guides/mcp-environment-lifecycle.md: MCPToolClient.list_tools() / call_tool() go to /mcp, so they don't run through step() or rewards; step(CallToolAction) is the training path; the 30 s default tool timeout.
• guides/runtime-providers.md: Kubernetes noted as planned outside the providers table; example field.
• guides/customizing-web-ui.md: documents custom_tab_name, custom_tab_primary, show_default_tab and title_override; the UI is off unless ENABLE_WEB_INTERFACE=true; current Gradio docs links.
• Tutorials: torchforge link (mcp-environment); format-compliance sentence matches its table (sft-warmup, page and notebook); drift explanation matches GRPO's default beta=0.0 (end-to-end-walkthrough); dtype= (wordle-grpo); TOC labels and the summary anchor (openenv-tutorial).
• Environment READMEs: client examples read result.observation (finqa, connect4, kernrl); websearch uses its WebSearchEnv client; finqa query names its columns; browsergym image ghcr.io/huggingface/openenv-browsergym-env; envs/... paths (snake, wildfire); client class names (openapp, finrl, browsergym).

The CLI template's sync client examples were checked and work as written (EnvClient supports with and resolves reset() without await), so they're unchanged.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation
• New environment
• Refactoring

Alignment Checklist

Before submitting, verify:

• I have read .claude/docs/PRINCIPLES.md and this PR aligns with our principles
• I have checked .claude/docs/INVARIANTS.md and no invariants are violated
• I have run /pre-submit-pr (or bash .claude/hooks/lint.sh and tests) and addressed all issues

RFC Status

• Not required (bug fix, docs, minor refactoring)
• RFC exists: #___
• RFC needed (will create before merge)

Test Plan

• Each fix was checked against the source (CLI options, client and discovery code, environment models and tools, the Docker workflow's image names) and the Hub (Space ids).
• scripts/sync_env_docs.py --check passes. tests/test_cli, tests/discovery, tests/scripts/test_sync_env_docs.py and tests/scripts/test_prepare_hf_deployment.py pass.
• ruff format --check reports the same files as on main (none of them changed by this PR).

Claude Code Review

N/A. This PR was written with AI assistance (Claude Code) and reviewed by me.

---

Note

Low Risk
Documentation-only changes with no production code paths modified; incorrect snippets could still mislead users until merged.

Overview
This PR updates documentation only so copy-pasted examples and CLI instructions match the current client, CLI, and manifest behavior—no runtime code changes.

Client and API patterns are corrected across README, guides, tutorials, and environment READMEs: reset()/step() examples use StepResult and read fields from result.observation (including Echo’s ready message via metadata["message"]). Legacy names are replaced where needed (EnvClient instead of HTTPEnvClient, WebSearchEnv instead of server-side WebSearchEnvironment). FinQA docs note that sql_query rejects SELECT * and expects named columns.

CLI and repo layout docs now reflect openenv push --repo-id, a positional environment directory, and expanded command lists (harbor, collect, catalog/discover, skills; serve removed where not implemented). Paths use envs/ (not src/envs/), contributing setup uses uv sync and PYTHONPATH=src:envs uv run pytest, and Hub examples use real Space ids (openenv/echo_env, etc.).

Guides refresh openenv.yaml / auto-discovery manifest shape, MCP lifecycle (call_tool/list_tools hit /mcp, not the reward step() loop), Gradio web UI options, Task API URL helpers, and minor tutorial fixes (torchforge link, dtype=, GRPO wording).

^{Reviewed by Cursor Bugbot for commit 4ab72fc. Bugbot is set up for automated code reviews on this repo. Configure here.}

[bot-ci-comment]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

[cursor]

Alignment Review Report

Automated Checks

• Lint: PASS (for this PR's files) — uv run ruff format src/ tests/ envs/ --check and uv run usort check src/ tests/ flag issues only in files this PR doesn't touch (55 pre-existing ruff format diffs plus the two usort files already called out in AGENTS.md — tests/envs/test_grid_world.py, tests/envs/test_julia_env.py). No .py files are changed by this PR (docs/README/notebook only), so Python lint has no bearing here.
• Debug code: CLEAN — check-debug.sh only surfaces pre-existing console.print/TODO hits in src/ that are untouched by this diff.

Open RFCs Context

RFCs currently Draft/In Review that touch areas this PR documents: RFC 006 (agentic RL harness interception, In Review), RFC 008 (environment auto-validation, In Review), RFC 010 (echo-env token world model, Draft), RFC 011 (ARD-backed catalog discovery, Draft), RFC 012 (Harbor capture providers, In Review). The PR documents the harbor, collect, catalog/discover, and skills CLI commands — these already exist and are registered in src/openenv/cli/__main__.py, so this is a docs-catch-up on shipped behavior, not a design decision that pre-empts any of these RFCs.

Tier 1: Fixes Required

None. I spot-checked a broad, representative sample of the claimed corrections against the current source and all were accurate:

• README.md: result.observation.metadata["message"] matches echo_environment.py's actual reset() observation (no echoed_message field exists); test_chess_environment.py exists, test_echo_environment.py does not; CLI list (harbor, collect, catalog, discover, skills present; serve genuinely unimplemented, confirmed by its own help="...TODO: Phase 4" string).
• push CLI: directory is a positional typer.Argument (not --directory), and --hardware/-H, --count/-n, --create-pr, --exclude all exist in push.py; no --tag flag exists (correctly dropped).
• environment-builder.md / concepts.md: template file is server/my_env_environment.py (confirmed via the __ENV_NAME___environment.py template naming), the openenv.yaml manifest shown matches envs/coding_env/openenv.yaml exactly (bare action:/observation: class names, no client: block).
• auto-discovery.md: AutoAction.from_hub is a real classmethod (src/openenv/auto/auto_action.py); from_env without hub install is deprecated in favor of it.
• mcp-environment-lifecycle.md: MCP_TOOL_CALL_TIMEOUT = 30.0 confirmed in mcp_environment.py; list_tools()/call_tool() going through /mcp rather than step() matches the implementation.
• concepts.md: "a client is locked to the mode it is first used in" matches the RuntimeError/mode-check in env_client.py.
• finqa_env README/doc: SELECT * really is rejected (tools.py returns "Error: SELECT * is not allowed").
• websearch_env README/doc: WebSearchEnv (not WebSearchEnvironment) is the actual exported client class in envs/websearch_env/__init__.py.
• Ran the test plan's own commands: PYTHONPATH=src:envs uv run pytest tests/test_cli tests/discovery tests/scripts/test_sync_env_docs.py tests/scripts/test_prepare_hf_deployment.py → 330 passed; python scripts/sync_env_docs.py --check → in sync.

I didn't find any uninitialized variables, missing imports, syntax errors, or credential exposure — expected, since this PR touches only Markdown/README/notebook files plus scripts/-adjacent doc stubs, no runtime code.

Tier 2: Alignment Discussion

Principle Conflicts

None identified. No change to the Gym-like API, no new reward logic, no client/server import changes — this PR only edits documentation prose and example snippets to match already-merged behavior.

RFC Conflicts

None identified. The CLI surface described (harbor, collect, catalog, discover, skills) is already implemented and registered in src/openenv/cli/__main__.py; documenting it doesn't make a design decision on behalf of RFC 006/008/010/011/012, it just reflects what's already shipped. Worth a human sanity check only on one point: RFC 011 (catalog/discover, still Draft) and RFC 012 (Harbor, In Review) are actively under design, so if either RFC's authors are mid-revision on CLI flags/behavior for those subcommands, it's worth confirming the one-line README.md descriptions here (openenv catalog/openenv discover — "Build and search environment catalogs"; openenv harbor — "Serve and run Harbor tasks with token-level capture") still match current intent before merge. This is a low-stakes heads-up, not a blocking concern.

ALIGNMENT FLAG: Doc text for catalog/discover/harbor commands touches areas with open RFCs

• Principle/RFC at stake: RFC 011 (ARD-backed catalog discovery, Draft, @thegovind) and RFC 012 (Harbor capture providers, In Review)
• The concern: These RFCs are still Draft/In Review, so their CLI surface could still shift; this PR's one-line README summaries should be re-checked against the RFCs' current direction before merge, even though they match the code as it exists today.
• Suggested reviewer: @thegovind (RFC 011 author); whoever authored/owns RFC 012 for Harbor

Summary

• 0 mechanical issues to fix
• 1 alignment point for human review (RFC-currency check, non-blocking)
• 0 RFC conflicts (the above is a "please double check," not a conflict)

Overall: this is an unusually well-verified documentation PR — every spot-checked claim (CLI flags, manifest format, client class names, observation field names, timeout constants, SQL validation behavior) matched the current source, and the test plan's own commands pass locally.

  

_{Sent by Cursor Automation: Pre-review}