[burtenshaw]

This PR reorganizes the docs into Concepts and Learn, updates the evaluation title, and fixes outdated examples and broken links.

[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]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Colab setup breaks on cell rerun
  • The setup now skips clone and chdir when already in the OpenEnv repository, allowing repeated Colab cell execution.

_{You can send follow-ups to the cloud agent here.}

[cursor]

APPROVE at 35069805

Docs + stub-sync refresh looks solid.

sync_env_docs._rewrite_relative_links

• Rewrites file/dir/image/HTML links to GitHub blob/tree/raw while preserving query/fragment, angle-bracket URLs, fenced/indented code, anchors, and external/missing/outside paths
• New regressions in tests/scripts/test_sync_env_docs.py pass (3/3); full tests/scripts/ 54/54
• scripts/sync_env_docs.py --check clean; check-env-docs CI green

Getting Started / Echo

• Replaces stale EchoAction / echoed_message with current MCP surface (metadata["message"], call_tool, CallToolAction / observation.result) — matches EchoEnv/MCPToolClient and SyncEnvClient.__getattr__ wrapping

Nav

• Concepts / Learn split; toctree locals all resolve; doc-builder PR build green

CI exact-head: tests 3.11/3.12, lint, package smoke, env locks, docs, CodeQL, snapshot — all green

Housekeeping: this supersedes fork #1101 (same README→docs relative-link problem, with broader coverage + tests). Safe to close #1101 after merge.

Docs/scripts only — not 0.6.0 wheel cargo.

View PR

  

_{Sent by Cursor Automation: Release}

[cursor]

REQUEST_CHANGES at 35069805 — withdrawing earlier APPROVE

Bugbot’s Colab finding is real and was introduced by this PR’s setup rewrite.

if IN_COLAB:
    if not Path("OpenEnv").exists():
        subprocess.check_call(["git", "clone", ...])
    os.chdir("OpenEnv")

After the first successful run, cwd is already the repo root, so Path("OpenEnv").exists() is false, the clone is skipped, and os.chdir("OpenEnv") fails on rerun.

Suggested shape:

if IN_COLAB:
    if (Path.cwd() / "pyproject.toml").exists():
        pass  # already in the repo
    elif Path("OpenEnv/pyproject.toml").exists():
        os.chdir("OpenEnv")
    else:
        subprocess.check_call(["git", "clone", "https://github.com/huggingface/OpenEnv.git"])
        os.chdir("OpenEnv")

Everything else from the prior APPROVE still looks good (link rewrite + tests, Echo API, nav, CI). Fix the Colab cell and I’ll re-approve.

  

_{Sent by Cursor Automation: Release}

[cursor]

APPROVE at 96e990fd

Colab blocker fixed: if IN_COLAB and Path.cwd().name != "OpenEnv": skips clone/chdir on cell rerun. Bugbot clean on this head.

Prior positives unchanged (link rewrite + tests, Echo API, nav; supersedes #1101). Docs/scripts only — not 0.6.0 wheel cargo.

View PR

  

_{Sent by Cursor Automation: Release}

[cursor]

Alignment Review Report

Two-tier review of the docs: refresh navigation changes (docs + the scripts/sync_env_docs.py link rewriter + new regression tests). Net: a clean PR that actually improves doc↔code alignment.

Automated Checks

• Lint: PASS — ruff format --check, ruff check, and usort check are all clean on the two changed Python files (scripts/sync_env_docs.py, tests/scripts/test_sync_env_docs.py). Note: .claude/hooks/lint.sh itself only errored on this review VM because uv isn't preinstalled here — I installed the tools and ran the underlying checks directly. CI lints src/+tests/, so the new test file is in scope and passes; scripts/ isn't CI-linted but is clean too.
• Debug code: CLEAN — check-debug.sh scans src/ only and surfaced pre-existing prints/TODOs; none are in this PR's changed files. The print()s in sync_env_docs.py are legitimate CLI output.
• Doc sync (python scripts/sync_env_docs.py --check): PASS — the committed docs/source/environments/*.md stubs are byte-identical to what the updated generator produces (verified on a clean tree).
• New tests: PASS — 3/3 in tests/scripts/test_sync_env_docs.py.
• Navigation: OK — every _toctree.yml local: target resolves to an existing file (no broken nav).

Open RFCs Context

Open RFCs on this branch — In Review: 000, 001, 002 (+ Cloud-Sandbox amendment), 003 (MCP), 005 (Agentic Harnesses), 008 (Env Auto-Validation), 012 (Harbor Capture Providers); Draft: 010, 011 (ARD Catalog Discovery); 004 (Rubrics) has no status header. None conflict with this PR. Two are relevant but consistent: the tutorial's HTTP→WebSocket rewrite matches the INVARIANTS "WebSocket for all environment communication" rule (HTTP is being deprecated), and getting-started's MCP call_tool usage matches RFC 003 "MCP as universal standard" / the dual-API boundary.

Tier 1: Fixes Required

None. All mechanical checks pass (lint / format / imports / tests / doc-sync).

Tier 2: Alignment Discussion

Principle Conflicts

None identified — the changes strengthen alignment rather than conflict:

• docs/source/guides/concepts.md: result.terminated → result.done fixes a reference to a non-existent attribute (client StepResult exposes done, client_types.py:28).
• docs/source/tutorials/openenv-tutorial.md: HTTP/REST framing → WebSocket, HTTPEnvClient→EnvClient, from core...→from openenv.core..., src/envs/→envs/ — all match the current API surface and the WebSocket invariant.
• docs/source/getting-started.md: switches to the MCP tool-calling pattern. Verified accurate against the code: MCPToolClient.call_tool unwraps the FastMCP envelope (.data, mcp_client.py:550), echo's reset sets metadata["message"]="Echo environment ready!" (echo_environment.py:133), and echo_message returns the message — so the # "..." output comments are correct.

RFC Conflicts

None identified. The docs touch RFC-governed areas (MCP / WebSocket) but describe them consistently with RFC 003 and the WebSocket invariant — this is convergence, not divergence.

Additional verification (high-value for a docs PR)

• State import in environment-builder.md resolves (env_server/types.py:180).
• cli.md: the Sphinx automodule → [[autodoc]] openenv.cli.commands.import_env.import_env swap targets a real symbol (import_env.py:58) and matches the [[autodoc]] syntax used everywhere else in that file.
• opencode.md / opencode_env/README.md drop a dead link to a non-existent DOCS/HF/... file (source README + synced stub stay consistent).

Minor (non-blocking)

• One optional heads-up left inline on the indented-code-block heuristic in _rewrite_relative_links.
• docs/README.md changes the local-preview hint to http://localhost:5173/index; worth a quick confirm that doc-builder preview serves at that path locally (doesn't affect the built site or CI).

Summary

• 0 mechanical issues to fix
• 0 alignment points for human review
• 0 RFC conflicts to discuss

Nice cleanup: generalizing the assets-only regex into a proper file/dir/image link rewriter (with query/fragment preservation, <...> autolinks, code-fence/inline-code skipping, and symlink/out-of-repo safety) and backing it with focused regression tests is a solid improvement.

  

_{Sent by Cursor Automation: Pre-review}

[cursor]

Optional (non-blocking): this treats any line indented ≥4 spaces (or a tab) as an indented code block and skips link rewriting for it. A relative link inside a deeply-indented list item would therefore not be rewritten and would stay relative (→ 404 on the docs site). The fenced-code handling just above is solid, and this matches all current READMEs (--check passes), so it's only a heads-up for future READMEs — not a blocker.

[cursor]

Stale comment

REQUEST_CHANGES at 96e990fd — correcting the prior approval

The navigation, link rewriting, focused tests, generated-doc sync, OpenSpiel Markdown walkthrough, and exact-head CI are otherwise green. Two concrete blockers remain:

1. The new AutoEnv quick start cannot install its package: openenv/echo-env resolves the live host but names a nonexistent Space git repository. The canonical repository is openenv/echo_env, but AutoEnv currently converts that to the wrong underscore hostname, so the docs-only working form needs the canonical repo plus an explicit https://openenv-echo-env.hf.space base URL (or a tested core resolver fix).
2. The new generic link parser makes sync_env_docs.py --fix destructive on malformed links. Reproduced with [bad](http://[): urlsplit raises ValueError after run_fix has opened the existing stub with "w", leaving the committed stub empty.

Also reconcile the runnable counterparts before merge: the Colab badge still opens examples/OpenEnv_Tutorial.ipynb, which pins old commit c2997e8 and teaches the legacy HTTP surface; the generate-openenv-env skill snapshots still retain stale tutorial content / nonexistent MyState; and the manual Echo Docker command maps 7860:7860 although the image listens on container port 8000.

Docs/scripts only — not 0.6.0 wheel cargo.

  

_{Sent by Cursor Automation: Release}

[cursor]

REQUEST_CHANGES at 1694071a (autofix progress)

Fixed this head:

• Getting Started AutoEnv now uses canonical openenv/echo_env + explicit https://openenv-echo-env.hf.space (with a regression).
• urlsplit malformed URLs fail-safe; --fix uses atomic temp+replace (no stub truncation); indented list link rewrite + tests.

CI: lint is already red — scripts/sync_env_docs.py and tests/scripts/test_sync_env_docs.py need ruff format (and the arc usort/ruff format pipeline).

Still open:

1. Nested image alts → misclassified as blob links (not raw).
2. unquote("%00") still crashes generation.
3. Blockquoted fenced code still has relative links rewritten.
4. Getting Started still documents -p 7860:7860 / localhost:7860 while the image listens on 8000, and still prints result.observation.result for MCP step() (CallToolResult dict). Root README.md still teaches nonexistent echoed_message (not in this PR’s file list, but it’s the wheel long description / TestPyPI surface).
5. CARLA maze_navigation.py --scenario maze-1 is invalid.
6. Git “complete working example” still treats bootstrap from_docker_image() as a connected client.

Prior notes on Colab notebook pin / generator skill MyState snapshots / tutorial TOC remain follow-ups. Not Thursday 0.6.0 wheel cargo.

  

_{Sent by Cursor Automation: Release}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: List rewrite misses nested fences
  • Fence detection now recognizes list-relative indentation, with regression coverage ensuring Markdown, href, and src targets remain unchanged.

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 8cc6a9c. Configure here.}

[cursor]

REQUEST_CHANGES at 7d5ce7df (most follow-ups fixed)

Fixed this head / prior autofix:

• Nested image alts, %00 path fail-safe, blockquoted fences, and list-nested fences now leave code/images alone (with tests).
• CARLA maze_navigation docs no longer pass invalid --scenario.
• Git README + examples/local_git_env.py resolve from_docker_image() via .sync().

Still open (Getting Started / package README):

1. docs/source/getting-started.md still runs -p 7860:7860 / connects to localhost:7860, but the Echo Space image listens on container port 8000 — use -p 7860:8000 (or map/connect to 8000 consistently).
2. Same page still print(result.observation.result) after MCP step(CallToolAction(...)); that value is a serialized CallToolResult dict (echoed string is under result["data"], or prefer call_tool as in the first example).
3. Root README.md still teaches nonexistent observation.echoed_message (wheel/TestPyPI long description). Not in this PR’s changed-file list, but it is the same broken quick-start surface.

Holding approval until the Getting Started docker/result-shape examples are corrected (and ideally the root README echo quick start). Exact-head CI still running. Not Thursday 0.6.0 wheel cargo.

View PR

  

_{Sent by Cursor Automation: Release}