docs(evaluator): document the Gym runner and fix the runner protocol

The Gym runner shipped with no documentation. "Gym" appeared nowhere in
`docs/`, even though `GymAgentTaskRunner` sits alongside the Callable and
Harbor runners in the SDK and `GymRunnerTarget` alongside Codex, Fabric, and
Harbor in the job spec.

Targets and Runners was also wrong about the one thing readers copy from it.
`AgentTaskRunner` is a two-member protocol -- `run_tasks` *and* `runner_info` --
but the page called it "the one-method protocol", showed only `run_tasks`, and
its `EchoRunner` example omitted `runner_info`. That example does not work:
being `@runtime_checkable`, the protocol rejects the class, and the run dies
with `NotImplementedError: unsupported agent-eval target type: EchoRunner`,
naming neither the protocol nor the missing method. Fixed, and the failure mode
is now stated so the error is searchable.

Adds "Evaluate a NeMo Gym Environment" beside the Harbor page, which had the
same shape already: an example README in `examples/gym/` and no doc. It covers
install and the `PATH` constraint, credentials, task discovery, the config
reference, results, output directories, the two-step Gym invocation, and
submission as a platform job.

Adds "Evaluate with a NeMo Fabric Harness" alongside it. Fabric was the other
shipped runner with no documentation at all -- absent from the whole `docs/`
tree despite covering four harnesses through one config. The page documents the
adapter map, the agent-config shape, the ATIF trajectory that distinguishes this
runner, and the sandboxed `FabricContainerRuntime`.

Codex and the OpenAI-Agents Docker sandbox are deliberately left undocumented:
the Codex runner is being removed in #1419, and `DockerSandboxAgentRuntime` is
stranded by the same PR (it existed only as the `sk-...`-key branch of ProfBench's
Codex path) and is expected to follow it.

The Fabric page is verified the same way: its config and run blocks execute
verbatim against a real Fabric -> Codex -> Relay evaluation, producing a
completed trial with an `atif` trajectory. That caught two defects in the draft --
`work_dir` needed a `Path`, and the example task declared `metrics=[]`, which the
evaluator rejects outright. `FabricContainerRuntime` is documented from source
rather than run: its own tests use a fake sandbox provider, so there was nothing
live to exercise.

Everything here was executed rather than read. A throwaway venv with
`nemo-gym` installed ran three live evaluations against mcqa, which caught four
errors in my own draft: `agent_config` was `configs/simple_agent.yaml` where the
real value is `responses_api_agents/simple_agent/configs/simple_agent.yaml`;
`result.summary.scores` does not iterate scores (`.scores.scores` does);
`work_dir` needs a `Path`; and the page never showed how to set an output
directory at all. The score names, the 0-100 vs 0-1 scale note, and the
`gym_run/` artifact list are copied from real output. The taskset-submission block
is executed verbatim in review too -- it stores five tasks from the bundled mcqa
dataset and the job side rebuilds all five rows from them. The submission snippet was
executed verbatim against #1315's branch, and two more traps came out of it: a
task cannot be named after `task.id` (a 64-char hash starting with a digit,
against a 63-char cap requiring a leading letter), and `GymRewardMetric` is not
a built-in type so the inline packager rejects it.

Two fixes outside the docs tree, both found while sourcing from the example:

`examples/gym/README.md` said to install Gym "in the same environment as the
SDK". The source says the opposite, and it is right -- Gym imports Ray at module
load and nemo-platform excludes Ray by constraint. Its "Next steps" also linked
`runtimes/gym_runtime.py`, which became the `runtimes/gym/` package; split into
live links to `config.py` and `runtime.py`.

The reuse guard's `FileExistsError` told the caller to "give each run a fresh
output_dir". There is no such parameter -- it is `AgentEvalRunConfig.work_dir`
-- so the message sent readers looking for an argument that does not exist.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Signed-off-by: Sandy Chapman <schapman@nvidia.com>

Author: SandyChapman

docs/evaluator/agent-eval/fabric-runner.mdx

@@ -0,0 +1,193 @@
+---
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+title: "Evaluate with a NeMo Fabric Harness"
+description: "Run a coding agent through NeMo Fabric and score it with agent-eval — one config selects the harness (Codex, Claude, Hermes), and Fabric returns an ATIF trajectory a metric can grade on."
+---
+
+[NeMo Fabric](https://github.com/nvidia/nemo-fabric) runs an agent **harness** rather than a single
+agent. Which harness runs is selected entirely by `config["harness"]["adapter_id"]`, so one runtime
+covers several agent frontends without changing your evaluation. Fabric returns an **ATIF
+trajectory** alongside the final answer, so a metric can score *how* the agent worked, not just what
+it answered.
+
+The result and bundle are the same as the
+[quickstart](/documentation/evaluate-models/agent-eval/quickstart) — only the runner changes.
+
+## Harnesses
+
+| `adapter_id` | Harness | Transport |
+|---|---|---|
+| `nvidia.fabric.codex` | Codex CLI | `cli` (subprocess) |
+| `nvidia.fabric.claude` | Claude | `cli` |
+| `nvidia.fabric.hermes` | Hermes SDK | `library` (in-process) |
+| `nvidia.fabric.langchain.deepagents` | LangChain deepagents | `library` |
+
+<Warning>
+
+This runner is **not** zero-dependency. It needs:
+
+- **The harness adapters**, from the `fabric` extra:
+
+  ```bash
+  uv sync --frozen --package nemo-evaluator-sdk --extra fabric --inexact
+  ```
+
+- **The `nemo-relay` gateway binary**, which captures the trajectory for out-of-process harnesses.
+  The pip package ships bindings only, so the daemon comes from a GitHub release asset:
+
+  ```bash
+  script/dev-install-fabric.sh
+  ```
+
+- **The harness's own CLI**, for `transport: cli` harnesses — `codex` on `PATH` and authenticated.
+
+The `fabric` extra installs the Codex, Claude, and Hermes adapters. The deepagents adapter is
+deliberately excluded from it, because that adapter does not support the Relay observability
+configuration Fabric streaming generates; install its harness separately if you need it.
+
+</Warning>
+
+## The agent config
+
+One mapping describes the whole agent — harness, runtime, environment, and model. This is a working
+Codex configuration:
+
+```python
+config = {
+    "schema_version": "fabric.agent/v1alpha1",
+    "metadata": {"name": "eval-fabric"},
+    "harness": {
+        "adapter_id": "nvidia.fabric.codex",
+        "resolution": "preinstalled",
+        "settings": {"sandbox": "workspace-write"},
+    },
+    "runtime": {
+        "mode": "oneshot",
+        "transport": "cli",
+        "input_schema": "text",
+        "output_schema": "message",
+        "timeout_seconds": 180,
+    },
+    "environment": {"provider": "local", "workspace": "ws"},
+    "models": {"default": {"provider": "openai", "model": "<model>"}},
+    "telemetry": {"enabled": False},
+}
+```
+
+Across harnesses the shape differs mainly in `adapter_id`, `runtime.transport`, and any
+harness-specific `harness.settings`. Codex runs as a subprocess (`transport: cli`) while the Hermes
+SDK harness runs in-library (`transport: library`). For complete Codex-CLI and Hermes-SDK
+configurations, see `examples/fabric_harness_runtimes.py` in the SDK.
+
+<Warning>
+
+**The Codex adapter requires an explicit model provider.** It does not fall back to the Codex CLI's
+own configured default, and starting without `models.default` fails the adapter lifecycle with
+`codex_invalid_configuration`.
+
+</Warning>
+
+Fold the complete configuration into this mapping. Fabric profile overlays are not used here.
+
+## Run it
+
+```python
+from pathlib import Path
+
+from nemo_evaluator_sdk.agent_eval.evaluator import AgentEvaluator
+from nemo_evaluator_sdk.agent_eval.runtimes.fabric.runtime import FabricAgentRuntime
+from nemo_evaluator_sdk import StringCheckMetric
+from nemo_evaluator_sdk.agent_eval.tasks import AgentEvalRunConfig, AgentEvalTask
+
+tasks = [
+    AgentEvalTask(
+        id="reply-ok",
+        intent="Reply with a fixed token.",
+        inputs={"instruction": "Reply with the word OK."},
+        metrics=[
+            StringCheckMetric(
+                operation="contains",
+                left_template="{{sample.output_text}}",
+                right_template="OK",
+            )
+        ],
+    )
+]
+
+runtime = FabricAgentRuntime(
+    config=config,
+    work_root="fabric",
+    capture_trajectory=True,
+)
+
+result = AgentEvaluator().run_sync(
+    tasks=tasks,
+    target=runtime,
+    config=AgentEvalRunConfig(work_dir=Path("out"), parallelism=1),
+)
+```
+
+### Configuration
+
+| Field | Required | Notes |
+|---|---|---|
+| `config` | yes | the agent config mapping above |
+| `model` | no | overrides `models.default.model` without editing the config |
+| `base_dir` | no | base directory for relative paths in the config |
+| `work_root` | no | where Fabric's per-run working directories are created |
+| `timeout_s` | no | overall run timeout, default `600` |
+| `capture_trajectory` | no | capture the ATIF trajectory as evidence, default `True` |
+| `trajectory_extra` | no | extra fields merged into the captured trajectory |
+| `runtime_name` | no | the name recorded on `runner_info`, default `fabric` |
+| `skills` | no | skills injected into the agent's workspace |
+| `task_hook` | no | a `FabricTaskRunHook` invoked around each task run |
+
+## The trajectory
+
+With `capture_trajectory=True`, each trial carries the agent's ATIF trajectory as **`trace`**
+evidence:
+
+```python
+trial = result.trials[0]
+assert trial.evidence is not None
+trace = trial.evidence.descriptors["trace"]
+# trace.format == "atif"; trace.ref is a path to the trajectory JSON, which has a "steps" key
+```
+
+That is what separates Fabric from the other runners: a metric can read the trajectory and score the
+agent's process — tool calls, reasoning, and observations — instead of only its final answer. See
+[Writing Metrics](/documentation/evaluate-models/agent-eval/writing-metrics) for reading evidence,
+and [Score by Component](/documentation/evaluate-models/agent-eval/score-by-component) for turning
+several signals into one reported score.
+
+## Running in a sandbox
+
+`FabricContainerRuntime` takes the same config and runs it inside a sandbox rather than on the host:
+
+```python
+from nemo_evaluator_sdk.agent_eval.runtimes.fabric.container_runtime import FabricContainerRuntime
+from nemo_evaluator_sdk.agent_eval.runtimes.sandbox.providers.docker import DockerSandboxProvider
+
+runtime = FabricContainerRuntime(config=config, provider=DockerSandboxProvider())
+```
+
+| Field | Required | Notes |
+|---|---|---|
+| `config` | yes | the same agent config, or a `FabricConfig` |
+| `provider` | yes | a `SandboxProvider` — `DockerSandboxProvider` or `DockerComposeSandboxProvider` |
+| `secrets` | no | secret references made available inside the sandbox |
+| `image` | no | override the sandbox image |
+| `skills` | no | skills injected into the agent's workspace |
+
+Use it when the agent should not run on the host — untrusted tasks, or a workspace that must be
+discarded per task. The host runtime is otherwise the simpler choice.
+
+## Next steps
+
+<Cards>
+  <Card title="Agent Evaluation (concepts)" href="/documentation/evaluate-models/agent-eval" />
+  <Card title="Targets and Runners" href="/documentation/evaluate-models/agent-eval/targets-and-runners" />
+  <Card title="Writing Metrics" href="/documentation/evaluate-models/agent-eval/writing-metrics" />
+</Cards>