config pages

docs/about/concepts/configuration.md

@@ -0,0 +1,60 @@
+(configuration-concepts)=
+
+# Configuration System
+
+NeMo Gym uses YAML configuration files to define which servers to run. Understanding the config structure helps you avoid common confusion when setting up training environments.
+
+## The Three-Level Pattern
+
+Every server definition follows this pattern:
+
+```yaml
+server_id:              # What YOU call it (your choice)
+  server_type:          # What KIND of server (matches a folder)
+    implementation:     # Which CODE to run (matches a subfolder)
+      entrypoint: ...
+```
+
+**Why three levels?** Each level serves a different purpose:
+
+| Level | You Control | Must Match |
+|-------|-------------|------------|
+| **Server ID** | ✅ Yes - name it anything | Nothing - it's your identifier |
+| **Server Type** | ❌ Pick from 3 options | `responses_api_models`, `resources_servers`, or `responses_api_agents` |
+| **Implementation** | ❌ Pick existing implementation | A folder inside that server type |
+
+### Understanding the Naming Pattern
+
+In many examples, you'll see the same name appear twice:
+
+```yaml
+example_simple_weather:        # ← Server ID
+  resources_servers:
+    example_simple_weather:    # ← Implementation
+```
+
+These serve different purposes:
+
+- **Server ID** (`example_simple_weather` on line 1): Your chosen identifier for this server instance. Used in API requests and when other servers reference it. You could name it `my_weather` or `weather_prod` instead.
+
+- **Implementation** (`example_simple_weather` on line 3): Must match the folder `resources_servers/example_simple_weather/`. This tells NeMo Gym which code to run.
+
+Examples often use matching names for simplicity, but the two values are independent choices.
+
+## Policy Model Variables
+
+NeMo Gym provides three standard placeholders for "the model being trained":
+
+- `policy_base_url` - Model API endpoint
+- `policy_api_key` - Authentication key
+- `policy_model_name` - Model identifier
+
+These let you reference the training model consistently across configs without hardcoding values. Define them once in `env.yaml`, then use `${variable_name}` syntax anywhere you need them.
+
+---
+
+:::{seealso}
+- {doc}`/reference/configuration` for complete syntax and field specifications
+- {doc}`/troubleshooting/configuration` for common errors
+:::
+

docs/about/concepts/index.md

@@ -38,6 +38,12 @@ Explore how resource servers score agent outputs with `verify()` implementations
 Essential vocabulary for agent training, RL workflows, and NeMo Gym. This glossary defines terms you'll encounter throughout the tutorials and documentation.
 :::
 
+:::{grid-item-card} {octicon}`gear;1.5em;sd-mr-1` Configuration System
+:link: configuration-concepts
+:link-type: ref
+Understand the three-level config pattern and why server IDs and implementations are independent choices.
+:::
+
 ::::
 
 ---
@@ -49,4 +55,5 @@ Essential vocabulary for agent training, RL workflows, and NeMo Gym. This glossa
 Core Abstractions <core-abstractions>
 Task Verification <task-verification>
 Key Terminology <key-terminology>
+Configuration System <configuration>
 ```

docs/about/index.md

@@ -15,9 +15,3 @@ Three components work together to generate and evaluate agent interactions:
 - **Models**: LLM inference endpoints (OpenAI-compatible or vLLM). Handle single-turn text generation and tool-calling decisions.
 - **Resources**: Provide tools (functions agents call) + verifiers (logic to score performance). Examples: math environments, code sandboxes, web search.
 
-```{toctree}
-:hidden:
-:maxdepth: 1
-
-Configuration System <configuration-system>
-```

docs/get-started/setup-installation.md

@@ -123,6 +123,7 @@ Replace `sk-your-actual-openai-api-key-here` with your real OpenAI API key. This
 - The model must support function calling (most GPT-4 models do)
 - Refer to [OpenAI's models documentation](https://platform.openai.com/docs/models) 🔗 for available models
 
+Refer to {doc}`/reference/configuration` for additional `env.yaml` options.
 :::
 
 :::{dropdown} Optional: Validate your API key before proceeding

docs/index.md

@@ -112,7 +112,6 @@ Home <self>
 about/index.md
 Concepts <about/concepts/index>
 Ecosystem <about/ecosystem>
-Configuration System <about/configuration-system>
 ```
 
 ```{toctree}
@@ -139,8 +138,18 @@ how-to-faq.md
 
 
 ```{toctree}
-:caption: Development
+:caption: Reference
 :hidden:
+:maxdepth: 1
 
+Configuration <reference/configuration>
 apidocs/index.rst
 ```
+
+```{toctree}
+:caption: Troubleshooting
+:hidden:
+:maxdepth: 1
+
+troubleshooting/configuration.md
+```