[Epic] Reduce environment authoring friction #2206

Related to #1520

Background

Authoring a new environment in Gym today creates friction at every step: auto-generated configs have no inline guidance, core component names are confusing, domain taxonomy is arbitrary, error messages are raw stack traces, and the scaffolding leaves a large gap to a working environment. This epic groups the open issues that address these authoring UX problems for the 0.7.0 release.

Sub-issues

Naming and terminology

• Add inline comments to auto-generated YAML configs for better developer UX #191 — Add inline comments to auto-generated YAML configs for better developer UX
• The word "Resources" is nebulous #395 — Rename "Resources Server" to a term that reflects its role (tools, environment state, and verification logic)
• bug: Lacks Guidance and Uses Unclear Taxonomy on Domain Values(e.g., agent) #600 — Revise domain taxonomy: values are unevenly scoped, unexplained, and non-intuitive
• proposal: reconsider the policy_ naming convention for model server config/env variables #1658 — Reconsider policy_ naming convention for model server config/env variables

Scaffolding and config authoring

• feat: init environment CLI with composable scaffolding #1029 — gym env init: composable scaffolding that closes the gap to a working environment
• Config UX: Reduce Nested Hierarchies, Split Definitions, and Cross-File String References #1700 — Config UX: reduce nested hierarchies, split definitions, and cross-file string references

First-run failure experience

• bug: nonexistent config path dumps raw FileNotFoundError traceback #1488 — Nonexistent config_paths dumps raw FileNotFoundError traceback instead of actionable error
• bug: ng_run with no config spawns Ray and hangs instead of failing fast #1489 — Omitting config_paths causes ng_run to spin up Ray and hang instead of failing fast
• Bug: Malformed +config_paths surfaces raw Pydantic ValidationError stack #1490 — Malformed config_paths surfaces raw Pydantic ValidationError stack trace

What this epic delivers

• gym env init-generated configs with inline comments explaining every field, valid values, and when to use them — no docs lookup required
• Consistent, meaningful names for core components across code, CLI, and documentation
• A coherent domain taxonomy with clear definitions and guidance
• Role-neutral model server config naming that works for eval and training users equally
• Scaffolding that produces a working environment skeleton, not just a starting point
• Actionable error messages at the first sign of a config problem — before Ray starts

Acceptance criteria

• Generated configs include inline comments on required fields, valid values, and purpose (closes Add inline comments to auto-generated YAML configs for better developer UX #191)
• "Resources Server" renamed consistently across code, CLI, and docs (closes The word "Resources" is nebulous #395)
• Domain taxonomy revised, scoped coherently, documented, and validated (closes bug: Lacks Guidance and Uses Unclear Taxonomy on Domain Values(e.g., agent) #600)
• policy_ prefix replaced with a role-neutral naming convention (closes proposal: reconsider the policy_ naming convention for model server config/env variables #1658)
• gym env init scaffolding closes the gap to a runnable environment (closes feat: init environment CLI with composable scaffolding #1029)
• Config nesting reduced; definitions and references simplified (closes Config UX: Reduce Nested Hierarchies, Split Definitions, and Cross-File String References #1700)
• Nonexistent config path produces a clear, actionable error before Ray starts (closes bug: nonexistent config path dumps raw FileNotFoundError traceback #1488)
• Missing config causes fast failure with a helpful message, not a Ray hang (closes bug: ng_run with no config spawns Ray and hangs instead of failing fast #1489)
• Malformed config_paths produces a clear error, not a Pydantic stack trace (closes Bug: Malformed +config_paths surfaces raw Pydantic ValidationError stack #1490)