From a7a43cae577f06c042773f37026d0be8e3684c4d Mon Sep 17 00:00:00 2001
From: lukass16 <lukasskellijs@gmail.com>
Date: Wed, 24 Jun 2026 16:59:20 -0700
Subject: [PATCH 01/16] fix(cli): make hud init blank write the local scaffold

The blank preset downloaded hud-evals/hud-blank (calculator + in-process
MCP example) instead of the simple letter-counting scaffold. Mark blank
as a local preset so it writes the bundled strawberry scaffold with no
network fetch, and document the behavior in the CLI reference.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/v6/reference/cli.mdx  | 182 +++++++++++++++++++++++++++++++++++++
 hud/cli/init.py            |  61 +++++++------
 hud/cli/presets.py         |  11 ++-
 hud/cli/tests/test_init.py |  21 +++++
 4 files changed, 243 insertions(+), 32 deletions(-)
 create mode 100644 docs/v6/reference/cli.mdx

diff --git a/docs/v6/reference/cli.mdx b/docs/v6/reference/cli.mdx
new file mode 100644
index 00000000..807bd9b6
--- /dev/null
+++ b/docs/v6/reference/cli.mdx
@@ -0,0 +1,182 @@
+---
+title: "CLI"
+description: "The hud command reference across the environment lifecycle."
+icon: "terminal"
+---
+
+Install the CLI with `uv tool install hud-python --python 3.12`. Authenticate once with `hud set HUD_API_KEY=...`.
+
+## Build & iterate
+
+### `hud init`
+
+Scaffold a new environment package in a fresh `<name>` directory. The `blank` template (the default with no preset, and the first option in the interactive picker) writes a minimal local scaffold - `env.py` (environment, templates, capabilities), `tasks.py` (concrete task rows), `Dockerfile.hud`, and `pyproject.toml` - no network, no API key. Every other preset downloads a starter environment from GitHub instead.
+
+```bash
+hud init                          # pick a template → ./<template>
+hud init my-env                   # pick a template (or minimal scaffold) → ./my-env
+hud init my-env --preset browser  # download the "browser" starter into ./my-env
+hud init --preset cua             # download the "cua" starter into ./cua-template
+hud init my-env --dir envs        # create ./envs/my-env
+```
+
+| Option | Description |
+|--------|-------------|
+| `--preset`, `-p` | Starter to use: `blank` (minimal local scaffold), `browser`, `cua`, `deepresearch`, `coding`, `ml`, `ml-triage`, `verilog`, `autonomous-businesses`, `gdpval`, `worldsim`, `videogamebench` (all downloaded from GitHub). Omit for the interactive picker (TTY); with a `NAME` in a non-interactive shell, omitting it writes the blank local scaffold. |
+| `--dir`, `-d` | Parent directory (default `.`). |
+| `--force`, `-f` | Overwrite existing files. |
+
+### `hud serve`
+
+Serve an environment's control channel locally (tcp JSON-RPC). `hud dev` is a
+deprecated alias.
+
+```bash
+hud serve               # auto-detect env.py
+hud serve env:env       # explicit module:attribute
+hud serve env.py -p 9000
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--port`, `-p` | `8765` | Port to serve on. |
+| `--host` | `127.0.0.1` | Interface to bind (use `0.0.0.0` inside containers). |
+| `--verbose`, `-v` | - | Detailed logs. |
+
+### `hud deploy`
+
+Build **and** publish to HUD infra in one step. The environment's name comes
+from the `Environment(...)` declaration in code; deploying the same name again
+rebuilds that environment.
+
+```bash
+hud deploy
+```
+
+| Option | Description |
+|--------|-------------|
+| `--all`, `-a` | Deploy all environments in the directory. |
+| `--env`, `-e` | Env var `KEY=VALUE` (repeatable). |
+| `--env-file` | Path to a `.env` file. |
+
+## Evaluate
+
+### `hud eval`
+
+The primary local iteration loop: run an agent over a task source (`.py`, directory, or JSON/JSONL), grade the result, and print the reward. Each rollout gets a **fresh subprocess** for the env - no shared state between tasks.
+
+```bash
+# Split layout (hud init): templates in env.py, task rows in tasks.py
+hud eval tasks.py claude
+hud eval tasks.py claude --full --group 3
+
+# Single-file layout: env + tasks list in one file
+hud eval env.py claude
+hud eval env.py claude --model claude-haiku-4-5   # cheaper model for fast iteration
+hud eval env.py claude --max-steps 30
+hud eval env.py claude --all                      # every task, not just the first
+hud eval env.py claude --full                     # every task, auto-respond, 100 steps
+```
+
+<Note>
+`hud eval` loads tasks from the path you pass. In a split project, point it at `tasks.py` (or `.` to scan the directory). It spawns `env.py` for the control channel automatically - you don't pass both files.
+</Note>
+
+**What you don't need for a local run:**
+- A HUD API key - local evals don't hit the platform
+- `hud serve` running - `hud eval` spawns the env subprocess for you
+- Docker - unless your env explicitly uses `DockerRuntime`
+- An SSH connection - the gateway timeout only applies when `env.workspace()` is declared
+
+For a platform taskset, pass its name or id directly: `hud eval "My Tasks" claude`. The tasks are fetched from the platform and the rollouts run remotely by default, since the env source is not on disk.
+
+**Single-task runs** show step-by-step progress (step number + tool calls). Multi-task batches are silent unless `--verbose` is passed.
+
+| Option | Description |
+|--------|-------------|
+| `--full` | Run the whole dataset (`--all --auto-respond --max-steps 100`). |
+| `--all` | Run every task instead of just the first. |
+| `--model`, `-m` | Model id. |
+| `--gateway`, `-g` | Force LLM calls through the HUD gateway. Implied when only `HUD_API_KEY` is set (no provider key); pass it to force the gateway when a provider key is also present. |
+| `--group` (alias `--group-size`) | Runs per task - a group of repeats whose reward spread you can inspect. |
+| `--max-concurrent` | Cap parallel rollouts. |
+| `--max-steps` | Cap steps per task (default 10). |
+| `--task-ids` | Comma-separated slugs or 0-based indices. |
+| `--config`, `-c` | Agent config `key=value` (repeatable). |
+| `--verbose`, `-v` | Show agent logs (step progress, tool calls) for batch runs too. |
+| `--very-verbose`, `-vv` | Debug-level logs. |
+| `--runtime` | Placement: `local`, `hud` (HUD runtime tunnel), or `tcp://host:port`. Defaults to `local` for a tasks file; platform tasksets default to remote hosted execution. |
+| `--remote` | Run the whole rollout remotely on the HUD platform. |
+| `--yes`, `-y` | Skip confirmation prompt. |
+
+## Run a packaged image
+
+`hud task start` / `hud task grade` attach to an env already serving locally (e.g. inside a built image, or alongside `hud serve`), or load one from source with `--source`. `hud task list` always reads from source (default `.`) - it doesn't attach.
+
+```bash
+hud task list                          # what tasks are exposed
+hud task start fix_bug                 # -> the prompt (stdout)
+hud task grade fix_bug --answer "..."  # -> the reward (stdout)
+```
+
+| Command | Key options |
+|---------|-------------|
+| `hud task start <task>` | `--source`/`-s`, `--args` (JSON), `--url`/`-u`, `--out`/`-o` |
+| `hud task grade <task>` | `--answer`, `--answer-file`, `--source`, `--args`, `--url`, `--out` |
+| `hud task list` | `--source`/`-s` |
+
+## Platform
+
+```bash
+hud sync tasks my-taskset      # publish tasks as a named taskset
+hud sync env                   # sync environment metadata
+```
+
+External benchmark formats (currently Harbor) load directly into the runtime
+as `Taskset`s - no conversion step. See [Harbor interop](/v6/advanced/harbor-convert).
+
+## Inspect
+
+### `hud jobs [<id>]`
+
+Without an id, lists your most recent jobs. With an id, lists every trace in that job.
+
+```bash
+hud jobs               # recent jobs - id, name, taskset, status, created
+hud jobs <job-id>      # traces for one job - trace id, status, reward, error
+hud jobs --json        # raw JSON
+hud jobs -n 50         # show up to 50 rows (default 20)
+```
+
+### `hud trace <trace_id>`
+
+Inspect a single rollout. Reads from the local telemetry JSONL file first
+(`HUD_TELEMETRY_LOCAL_DIR/<trace_id>.jsonl`) and falls back to the platform API.
+
+```bash
+hud trace <trace-id>          # rendered view: agent turns, tool calls, tool results
+hud trace <trace-id> --json   # raw event list
+```
+
+Set `HUD_TELEMETRY_LOCAL_DIR` in your environment to write spans to disk during a
+rollout so `hud trace` can read them offline without an API call.
+
+## Other commands
+
+| Command | Description |
+|---------|-------------|
+| `hud set KEY=VALUE` | Persist credentials/vars to `~/.hud/.env`. |
+| `hud login` | Authenticate with HUD. |
+| `hud models list` | List gateway models. |
+| `hud models fork <model> --name <slug>` | Fork a trainable model from an existing one. |
+| `hud models checkpoints <model>` | List a model's checkpoint tree. |
+| `hud models head <model> [--set <checkpoint-id>]` | Show - or set (rollback/select) - a model's active checkpoint. |
+| `hud cancel` | Cancel a running job. |
+| `hud version` | Show the CLI version. |
+
+## See also
+
+<CardGroup cols={2}>
+<Card title="Quickstart" icon="bolt" href="/v6/start/quickstart" />
+<Card title="Run & deploy" icon="rocket" href="/v6/reference/runtime" />
+</CardGroup>
diff --git a/hud/cli/init.py b/hud/cli/init.py
index 64556c9f..a665ccad 100644
--- a/hud/cli/init.py
+++ b/hud/cli/init.py
@@ -3,9 +3,10 @@
 With no ``NAME`` it shows an interactive picker of the starter environments and
 clones the chosen one from GitHub into ``./<repo>`` — the same set the platform's
 *environments/new* flow offers (see :mod:`hud.cli.presets`). With a ``NAME`` it
-scaffolds into ``./NAME``: the picker also offers a minimal local scaffold (no
-network, no API key), which is the default in a non-interactive shell. ``--preset``
-skips the picker and downloads that starter directly.
+scaffolds into ``./NAME``. The ``blank`` starter is special: it writes the bundled
+minimal scaffold (no network, no API key) — a tiny letter-counting task — rather
+than downloading anything. That same scaffold is the default in a non-interactive
+shell when a ``NAME`` is given. ``--preset`` skips the picker.
 """
 
 from __future__ import annotations
@@ -24,8 +25,6 @@
 from .presets import ENVIRONMENT_PRESETS, PRESETS_BY_ID, EnvironmentPreset, materialize_preset
 from .templates import DOCKERFILE_HUD, ENV_PY, PYPROJECT_TOML, TASKS_PY
 
-_LOCAL_SCAFFOLD = "__local__"
-
 
 def _python_name(name: str) -> str:
     """Normalize a package name into a Python-identifier-ish env name."""
@@ -33,16 +32,13 @@ def _python_name(name: str) -> str:
     return "".join(c if c.isalnum() or c == "_" else "_" for c in name)
 
 
-def _resolve_preset(
-    preset: str | None, hud_console: HUDConsole, *, allow_local: bool
-) -> EnvironmentPreset | None:
+def _resolve_preset(preset: str | None, hud_console: HUDConsole) -> EnvironmentPreset | None:
     """Pick the starter: an explicit ``--preset`` id, an interactive choice, or
-    ``None`` for the minimal local scaffold.
+    ``None`` when there's no TTY to prompt.
 
-    ``allow_local`` offers the bundled local scaffold in the interactive picker.
-    It needs a target name, so it's only offered when the caller has one (i.e. a
-    ``NAME`` was passed). With no name the picker lists only the GitHub starters,
-    whose repo name becomes the target directory.
+    The ``blank`` starter (``local=True``) writes the bundled minimal scaffold; the
+    rest are downloaded from GitHub, with the repo name becoming the target
+    directory when no ``NAME`` is given.
     """
     if preset is not None:
         chosen = PRESETS_BY_ID.get(preset)
@@ -52,7 +48,8 @@ def _resolve_preset(
             raise typer.Exit(1)
         return chosen
 
-    # No flag: pick interactively when we have a TTY, else the local scaffold.
+    # No flag: pick interactively when we have a TTY, else fall back to the caller's
+    # local-scaffold default (only reachable when a NAME was passed).
     if not (sys.stdin.isatty() and sys.stdout.isatty()):
         return None
 
@@ -60,11 +57,8 @@ def _resolve_preset(
         {"name": f"{p.emoji}  {p.name} — {p.description}", "value": p.id}
         for p in ENVIRONMENT_PRESETS
     ]
-    if allow_local:
-        local = {"name": "💾  Minimal (local scaffold, no download)", "value": _LOCAL_SCAFFOLD}
-        choices.insert(0, local)
     selected = hud_console.select("Choose a template", choices, default=0, spaced=True)
-    return None if selected == _LOCAL_SCAFFOLD else PRESETS_BY_ID[selected]
+    return PRESETS_BY_ID[selected]
 
 
 def _ensure_writable(target: Path, force: bool, hud_console: HUDConsole) -> None:
@@ -100,21 +94,24 @@ def init_command(
         None,
         "--preset",
         "-p",
-        help="Template to download from GitHub (e.g. blank, browser, cua, "
-        "deepresearch, coding, ml, verilog). Omit for the interactive picker; with "
-        "a NAME in a non-interactive shell, omitting it writes the minimal local scaffold.",
+        help="Template to use (e.g. blank, browser, cua, deepresearch, coding, ml, "
+        "verilog). 'blank' writes a minimal local scaffold; the rest download from "
+        "GitHub. Omit for the interactive picker; with a NAME in a non-interactive "
+        "shell, omitting it writes the blank local scaffold.",
     ),
 ) -> None:
     """🚀 Create a new HUD environment package.
 
-    [not dim]With no NAME, pick a template and clone it into the current directory
-    (as ./<template>). With a NAME, scaffold into ./NAME — pick a template, or
-    write the minimal local scaffold (env.py, tasks.py, Dockerfile.hud,
-    pyproject.toml). Pass --preset to skip the picker.
+    [not dim]With no NAME, pick a template and put it in the current directory
+    (as ./<template>). With a NAME, scaffold into ./NAME. The 'blank' template
+    writes a minimal local scaffold (env.py, tasks.py, Dockerfile.hud,
+    pyproject.toml); every other template downloads from GitHub. Pass --preset to
+    skip the picker.
 
     Examples:
         hud init                          # pick a template → ./<template>
-        hud init my-env                   # pick a template (or minimal) → ./my-env
+        hud init my-env                   # pick a template → ./my-env
+        hud init my-env --preset blank    # minimal local scaffold → ./my-env
         hud init my-env --preset browser  # clone the browser template → ./my-env
         hud init --preset cua             # clone the cua template → ./cua-template[/not dim]
     """
@@ -125,12 +122,16 @@ def init_command(
     if explicit_target is not None:
         _ensure_writable(explicit_target, force, hud_console)
 
-    chosen = _resolve_preset(preset, hud_console, allow_local=name is not None)
+    chosen = _resolve_preset(preset, hud_console)
+
+    # ``blank`` (and the non-interactive no-preset default) writes the bundled
+    # local scaffold; every other preset is downloaded from GitHub.
+    is_download = chosen is not None and not chosen.local
 
     if explicit_target is not None:
         target = explicit_target
     elif chosen is not None:
-        # No name: clone the template into ./<repo>, like `git clone` would.
+        # No name: create ./<repo> (clone target for downloads, or the blank dir).
         target = Path(directory) / chosen.repo
         _ensure_writable(target, force, hud_console)
     else:
@@ -141,7 +142,7 @@ def init_command(
         raise typer.Exit(1)
 
     hud_console.header(f"HUD Init: {target.name}")
-    if chosen is not None:
+    if is_download and chosen is not None:
         hud_console.info(f"Downloading {chosen.owner}/{chosen.repo} …")
         created = not target.exists()
         try:
@@ -162,7 +163,7 @@ def init_command(
     hud_console.info("")
     hud_console.command_example(f"cd {target}", "1. Enter the package")
     hud_console.info("")
-    if chosen is not None:
+    if is_download:
         hud_console.info("2. Read the README for this starter's setup + tasks.")
         hud_console.info("")
         hud_console.command_example("hud eval tasks.py claude", "3. Run an agent over the tasks")
diff --git a/hud/cli/presets.py b/hud/cli/presets.py
index 3c3eb2b1..32384a77 100644
--- a/hud/cli/presets.py
+++ b/hud/cli/presets.py
@@ -23,7 +23,12 @@
 
 @dataclass(frozen=True, slots=True)
 class EnvironmentPreset:
-    """A starter environment sourced from a public GitHub repo."""
+    """A starter environment.
+
+    Most presets are sourced from a public GitHub repo. When ``local`` is set the
+    starter is the bundled minimal scaffold instead (see :mod:`hud.cli.templates`);
+    ``owner``/``repo`` are then only used to name the target directory.
+    """
 
     id: str
     emoji: str
@@ -31,6 +36,7 @@ class EnvironmentPreset:
     description: str
     owner: str
     repo: str
+    local: bool = False
 
 
 ENVIRONMENT_PRESETS: tuple[EnvironmentPreset, ...] = (
@@ -38,9 +44,10 @@ class EnvironmentPreset:
         "blank",
         "🧱",
         "Blank",
-        "Minimal starting point for building your own environment.",
+        "Minimal local scaffold (no download): a single letter-counting task.",
         "hud-evals",
         "hud-blank",
+        local=True,
     ),
     EnvironmentPreset(
         "browser",
diff --git a/hud/cli/tests/test_init.py b/hud/cli/tests/test_init.py
index 69e94082..1e4f8710 100644
--- a/hud/cli/tests/test_init.py
+++ b/hud/cli/tests/test_init.py
@@ -53,6 +53,27 @@ def test_init_scaffolds_a_runnable_package(tmp_path: Path) -> None:
     assert '"dev"' not in dockerfile
 
 
+def test_init_blank_preset_writes_local_scaffold_without_network(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    # 'blank' is the bundled local scaffold: it must never hit the network.
+    def _boom(*args: object, **kwargs: object) -> None:
+        raise AssertionError("materialize_preset should not be called for blank")
+
+    monkeypatch.setattr(init_module, "materialize_preset", _boom)
+
+    init_command(name="berry", directory=str(tmp_path), force=False, preset="blank")
+
+    target = tmp_path / "berry"
+    assert {p.name for p in target.iterdir()} == {
+        "pyproject.toml",
+        "env.py",
+        "tasks.py",
+        "Dockerfile.hud",
+    }
+    assert 'Environment(name="berry")' in (target / "env.py").read_text()
+
+
 def test_init_refuses_to_clobber_nonempty_directory(tmp_path: Path) -> None:
     target = tmp_path / "taken"
     target.mkdir()

From c5c71321cbbf6c419f4975d2efcbe61073579390 Mon Sep 17 00:00:00 2001
From: lukass16 <lukasskellijs@gmail.com>
Date: Wed, 24 Jun 2026 16:59:21 -0700
Subject: [PATCH 02/16] docs(v6): restructure navigation and reference pages

Move core docs into reference/, relocate protocol under advanced/, drop
the old build overview page, and update docs.json, skill.md, and
cross-links across cookbooks, FAQ, and start pages.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/docs.json                               |  43 ++--
 docs/skill.md                                |  48 ++--
 docs/v6/advanced/extending.mdx               |  28 +--
 docs/v6/advanced/harbor-convert.mdx          |  10 +-
 docs/v6/{core => advanced}/protocol.mdx      |  16 +-
 docs/v6/advanced/robots.mdx                  |   2 +-
 docs/v6/build/overview.mdx                   | 221 -------------------
 docs/v6/cookbooks/coding-agent.mdx           |   8 +-
 docs/v6/cookbooks/ops-diagnostics.mdx        |  10 +-
 docs/v6/cookbooks/robot-benchmark.mdx        |   2 +-
 docs/v6/core/cli.mdx                         | 182 ---------------
 docs/v6/more/faq.mdx                         |  22 +-
 docs/v6/more/migrate-v6.mdx                  |   8 +-
 docs/v6/{core => reference}/advice.mdx       |  10 +-
 docs/v6/{core => reference}/agents.mdx       |  14 +-
 docs/v6/{core => reference}/capabilities.mdx |   8 +-
 docs/v6/{core => reference}/environment.mdx  |  24 +-
 docs/v6/{core => reference}/graders.mdx      |   4 +-
 docs/v6/{core => reference}/runtime.mdx      |   8 +-
 docs/v6/{core => reference}/tasks.mdx        |  26 +--
 docs/v6/{core => reference}/training.mdx     |  18 +-
 docs/v6/{core => reference}/types.mdx        |   6 +-
 docs/v6/start/index.mdx                      |  10 +-
 docs/v6/start/quickstart.mdx                 |  19 +-
 24 files changed, 166 insertions(+), 581 deletions(-)
 rename docs/v6/{core => advanced}/protocol.mdx (81%)
 delete mode 100644 docs/v6/build/overview.mdx
 delete mode 100644 docs/v6/core/cli.mdx
 rename docs/v6/{core => reference}/advice.mdx (95%)
 rename docs/v6/{core => reference}/agents.mdx (89%)
 rename docs/v6/{core => reference}/capabilities.mdx (97%)
 rename docs/v6/{core => reference}/environment.mdx (91%)
 rename docs/v6/{core => reference}/graders.mdx (97%)
 rename docs/v6/{core => reference}/runtime.mdx (96%)
 rename docs/v6/{core => reference}/tasks.mdx (90%)
 rename docs/v6/{core => reference}/training.mdx (95%)
 rename docs/v6/{core => reference}/types.mdx (95%)

diff --git a/docs/docs.json b/docs/docs.json
index c326f21a..4a117704 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -66,11 +66,15 @@
             "version": "v6",
             "default": true,
             "groups": [
-              { "group": "Start here", "pages": ["v6/start/index", "v6/start/quickstart"] },
-              { "group": "Overview", "pages": ["v6/build/overview", "v6/core/protocol"] },
-              { "group": "Core", "pages": ["v6/core/environment", "v6/core/tasks", "v6/core/capabilities", "v6/core/agents", "v6/core/runtime", "v6/core/graders", "v6/core/advice", "v6/core/training", "v6/core/types", "v6/core/cli"] },
-              { "group": "Advanced", "pages": ["v6/advanced/extending", "v6/advanced/robots", "v6/advanced/harbor-convert"] },
-              { "group": "Cookbooks", "pages": ["v6/cookbooks/index", "v6/cookbooks/coding-agent", "v6/cookbooks/ops-diagnostics", "v6/cookbooks/a2a-chat", "v6/cookbooks/robot-benchmark"] },
+              { "group": "Start here", "pages": ["v6/start/index", "v6/start/quickstart", "v6/start/overview"] },
+              { "group": "Guides", "pages": ["v6/guides/creating-an-environment", "v6/guides/running-an-eval", "v6/guides/training-models", "v6/guides/split-layout-demo"] },
+              { "group": "Reference", "pages": ["v6/reference/environment", "v6/reference/tasks", "v6/reference/capabilities", "v6/reference/agents", "v6/reference/runtime", "v6/reference/graders", "v6/reference/training", "v6/reference/types", "v6/reference/cli"] },
+              { "group": "Advanced", "pages": [
+                { "group": "Advanced", "expanded": false, "pages": ["v6/advanced/protocol", "v6/advanced/extending", "v6/reference/advice", "v6/advanced/robots", "v6/advanced/harbor-convert"] }
+              ] },
+              { "group": "Cookbooks", "pages": [
+                { "group": "Cookbooks", "expanded": false, "pages": ["v6/cookbooks/index", "v6/cookbooks/coding-agent", "v6/cookbooks/ops-diagnostics", "v6/cookbooks/a2a-chat", "v6/cookbooks/robot-benchmark"] }
+              ] },
               { "group": "More", "pages": ["v6/more/faq", "v6/more/migrate-v6", "v6/more/contributing"] }
             ]
           }
@@ -86,25 +90,26 @@
     { "source": "/v6/contributing", "destination": "/v6/more/contributing" },
     { "source": "/v6/index", "destination": "/v6/start/index" },
     { "source": "/v6/quickstart", "destination": "/v6/start/quickstart" },
-    { "source": "/v6/protocol", "destination": "/v6/core/protocol" },
-    { "source": "/v6/reference/:slug*", "destination": "/v6/core/:slug*" },
-    { "source": "/v6/build/protocol", "destination": "/v6/core/protocol" },
+    { "source": "/v6/protocol", "destination": "/v6/advanced/protocol" },
+    { "source": "/v6/core/protocol", "destination": "/v6/advanced/protocol" },
+    { "source": "/v6/build/protocol", "destination": "/v6/advanced/protocol" },
     { "source": "/v6/core/robots", "destination": "/v6/advanced/robots" },
-    { "source": "/v6/build/environments", "destination": "/v6/core/environment" },
-    { "source": "/v6/build/tasks", "destination": "/v6/core/tasks" },
-    { "source": "/v6/build/agents", "destination": "/v6/core/agents" },
-    { "source": "/v6/build/run", "destination": "/v6/core/runtime" },
-    { "source": "/v6/build/train", "destination": "/v6/core/training" },
-    { "source": "/v6/build/advice", "destination": "/v6/core/advice" },
-    { "source": "/v6/run/models", "destination": "/v6/core/agents" },
-    { "source": "/v6/run/deploy", "destination": "/v6/core/runtime" },
-    { "source": "/v6/run/training", "destination": "/v6/core/training" },
-    { "source": "/v6/run/signal", "destination": "/v6/core/advice" },
+    { "source": "/v6/core/:slug*", "destination": "/v6/reference/:slug*" },
+    { "source": "/v6/build/environments", "destination": "/v6/reference/environment" },
+    { "source": "/v6/build/tasks", "destination": "/v6/reference/tasks" },
+    { "source": "/v6/build/agents", "destination": "/v6/reference/agents" },
+    { "source": "/v6/build/run", "destination": "/v6/reference/runtime" },
+    { "source": "/v6/build/train", "destination": "/v6/reference/training" },
+    { "source": "/v6/build/advice", "destination": "/v6/reference/advice" },
+    { "source": "/v6/run/models", "destination": "/v6/reference/agents" },
+    { "source": "/v6/run/deploy", "destination": "/v6/reference/runtime" },
+    { "source": "/v6/run/training", "destination": "/v6/reference/training" },
+    { "source": "/v6/run/signal", "destination": "/v6/reference/advice" },
     { "source": "/v6/advanced/integrations", "destination": "/v6/advanced/extending" },
     { "source": "/v6/advanced/patterns", "destination": "/v6/advanced/extending" },
     { "source": "/v6/advanced/chat", "destination": "/v6/advanced/extending" },
     { "source": "/v6/advanced/subagents", "destination": "/v6/advanced/extending" },
-    { "source": "/v6/start/overview", "destination": "/v6/build/overview" },
+    { "source": "/v6/build/overview", "destination": "/v6/start/overview" },
     { "source": "/cookbooks/ops-diagnostics", "destination": "/v6/cookbooks/ops-diagnostics" },
     { "source": "/cookbooks/codex-coding", "destination": "/v6/cookbooks/coding-agent" },
     { "source": "/cookbooks/:slug*", "destination": "/v6/start/quickstart" }
diff --git a/docs/skill.md b/docs/skill.md
index 945a32ae..d230ff74 100644
--- a/docs/skill.md
+++ b/docs/skill.md
@@ -50,7 +50,7 @@ tasks = [count_letter(word=w) for w in ("strawberry", "raspberry", "blueberry")]
 ```
 
 Run it: `hud eval tasks.py claude`. Cite [Quickstart](/v6/start/quickstart)
-and [Tasks](/v6/core/tasks).
+and [Tasks](/v6/reference/tasks).
 
 **Capabilities** give the agent something to act on (declare on the env; the
 harness brings its own tools):
@@ -64,8 +64,8 @@ env.workspace("/workspace")
 
 `ssh` (shell+files; `env.workspace(root)` runs the sandbox for you),
 `mcp`, `cdp` (browser), `rfb` (computer-use), `robot` (robot policies). Cite
-[Environments](/v6/core/environment) and
-[Capabilities](/v6/core/capabilities).
+[Environments](/v6/reference/environment) and
+[Capabilities](/v6/reference/capabilities).
 
 ### MCP capability — in-process tool server
 
@@ -113,10 +113,10 @@ async def my_task(param: str = "default"):
 ```
 
 The agent sees MCP tools alongside HUD's own harness tools — no extra wiring
-needed in the template. Cite [Capabilities](/v6/core/capabilities).
+needed in the template. Cite [Capabilities](/v6/reference/capabilities).
 
-**Run / scale / train:** [Models](/v6/core/agents),
-[Deploy](/v6/core/runtime), [Training](/v6/core/training).
+**Run / scale / train:** [Models](/v6/reference/agents),
+[Deploy](/v6/reference/runtime), [Training](/v6/reference/training).
 
 ---
 
@@ -171,7 +171,7 @@ for model in ["claude-opus-4-8", "claude-sonnet-4-6", "gpt-5.4"]:
     print(f"{model}: {job.reward:.2f}")
 ```
 
-Cite [Deploy](/v6/core/runtime), [Models](/v6/core/agents), [Training](/v6/core/training).
+Cite [Deploy](/v6/reference/runtime), [Models](/v6/reference/agents), [Training](/v6/reference/training).
 
 ---
 
@@ -286,7 +286,7 @@ For an existing v5 env, follow [Migrate to v6](/v6/more/migrate-v6).
 ## Task-quality doctrine — push back when you see these
 
 For each trigger: **what to tell the user**, then **the page to cite**. The
-canonical reference is [Designing tasks for signal](/v6/core/advice).
+canonical reference is [Designing tasks for signal](/v6/reference/advice).
 
 ### 1. Constant / echo / shape-only grader → reward hacking
 
@@ -300,8 +300,8 @@ rewarded is exploited. Grade **substance, not surface form**: credit a correct
 answer in a different format, but never credit the shape alone. The cheapest
 path that scores *without doing the work* must sit at or below the floor.
 
-**Cite:** [/v6/core/advice](/v6/core/advice) ("Resist the cheapest
-path"), [Graders](/v6/core/graders).
+**Cite:** [/v6/reference/advice](/v6/reference/advice) ("Resist the cheapest
+path"), [Graders](/v6/reference/graders).
 
 ### 2. All-equal rewards → no within-group spread
 
@@ -316,8 +316,8 @@ of trainability is *within-group spread*, not the mean. Run a group
 All-one (saturated) is wasted surface; all-zero at small group sizes may still
 be learnable at training scale, but investigate it.
 
-**Cite:** [/v6/core/advice](/v6/core/advice) ("Signal lives in
-within-group spread"), [Training](/v6/core/training).
+**Cite:** [/v6/reference/advice](/v6/reference/advice) ("Signal lives in
+within-group spread"), [Training](/v6/reference/training).
 
 ### 3. Public-benchmark substrate → contamination
 
@@ -332,7 +332,7 @@ codebase operated to generate fresh logs), but not handed to the agent verbatim.
 Keep real failures and edge cases — they're the signal; don't fabricate
 synthetic substrate to look real.
 
-**Cite:** [/v6/core/advice](/v6/core/advice) ("Source substrate that
+**Cite:** [/v6/reference/advice](/v6/reference/advice) ("Source substrate that
 isn't memorized").
 
 ### 4. Single-shot task → needs multi-step
@@ -347,7 +347,7 @@ and a problem that requires integrating evidence across more than one
 observation (the [ops-diagnostics](/v6/cookbooks/ops-diagnostics) cookbook is a
 model example).
 
-**Cite:** [/v6/core/advice](/v6/core/advice) ("Make it multi-step").
+**Cite:** [/v6/reference/advice](/v6/reference/advice) ("Make it multi-step").
 
 ### 5. Comparing only similar top models → need a spanning set
 
@@ -360,7 +360,7 @@ task can look broken. Evaluate against a deliberate **weak anchor and a strong
 anchor**, not a cluster of top performers. Also state the model+reasoning regime
 you calibrated against; difficulty has no absolute meaning.
 
-**Cite:** [/v6/core/advice](/v6/core/advice) ("Difficulty is relative to
+**Cite:** [/v6/reference/advice](/v6/reference/advice) ("Difficulty is relative to
 a specific model").
 
 ### 6. Same-shape taskset → needs diversity
@@ -374,7 +374,7 @@ substrate sources, deliverable shapes, and capabilities exercised**, and spread
 the **difficulty distribution** (don't pile up at score 0 or saturation). Size
 the set to the training run so it doesn't overfit in the first few steps.
 
-**Cite:** [/v6/core/advice](/v6/core/advice) ("Compose a taskset that
+**Cite:** [/v6/reference/advice](/v6/reference/advice) ("Compose a taskset that
 isn't all one shape").
 
 ### 7. Answer leakage in the environment or prompt
@@ -387,7 +387,7 @@ eval, or author oracle/grading scripts left readable.
 root-cause leaks, keep grader-only vocabulary out of the prompt (weave needed
 context naturally), don't imply it's a test, and strip author artifacts.
 
-**Cite:** [/v6/core/advice](/v6/core/advice) ("Keep the answer out of
+**Cite:** [/v6/reference/advice](/v6/reference/advice) ("Keep the answer out of
 the environment").
 
 ### 8. Prompt ↔ grader misalignment
@@ -400,8 +400,8 @@ Enforce score–quality monotonicity: better substantive work must never score
 lower. Compose graders with `combine` so subscores make a partial reward
 legible and monotonicity violations visible.
 
-**Cite:** [/v6/core/advice](/v6/core/advice) ("Align the prompt and the
-grader"), [Graders](/v6/core/graders).
+**Cite:** [/v6/reference/advice](/v6/reference/advice) ("Align the prompt and the
+grader"), [Graders](/v6/reference/graders).
 
 ---
 
@@ -414,7 +414,7 @@ grader"), [Graders](/v6/core/graders).
 - Compose: `await combine(...)` (positive weights normalize to 1.0).
 - Structured answers: `@env.template(returns=MyModel)` → answer is `Answer[T]`.
 
-Cite [Graders](/v6/core/graders) and [Types](/v6/core/types).
+Cite [Graders](/v6/reference/graders) and [Types](/v6/reference/types).
 
 ---
 
@@ -440,7 +440,7 @@ Set `HUD_TELEMETRY_LOCAL_DIR` to write spans locally; `hud trace` reads from dis
 first and falls back to the platform API. Cite [CLI](/v6/reference/cli).
 
 When unsure about an API, read the page rather than guess:
-[Environment](/v6/core/environment) · [Tasks & Tasksets](/v6/core/tasks) ·
-[Capabilities](/v6/core/capabilities) · [Agents](/v6/core/agents) ·
-[Graders](/v6/core/graders) · [Types](/v6/core/types) ·
-[CLI](/v6/core/cli).
+[Environment](/v6/reference/environment) · [Tasks & Tasksets](/v6/reference/tasks) ·
+[Capabilities](/v6/reference/capabilities) · [Agents](/v6/reference/agents) ·
+[Graders](/v6/reference/graders) · [Types](/v6/reference/types) ·
+[CLI](/v6/reference/cli).
diff --git a/docs/v6/advanced/extending.mdx b/docs/v6/advanced/extending.mdx
index 77e46d3f..02ec4c80 100644
--- a/docs/v6/advanced/extending.mdx
+++ b/docs/v6/advanced/extending.mdx
@@ -11,9 +11,9 @@ chats. Each is independent; jump to what you need.
 
 ## Bring your own harness
 
-Because an [environment](/v6/core/environment) only exposes [capabilities](/v6/core/capabilities) and
+Because an [environment](/v6/reference/environment) only exposes [capabilities](/v6/reference/capabilities) and
 never a fixed agent, any loop or framework plugs in as a harness. Wrapping one is a thin adapter, not
-protocol work: you get a [`Run`](/v6/core/types#run), drive the environment off it, and fill
+protocol work: you get a [`Run`](/v6/reference/types#run), drive the environment off it, and fill
 `run.trace.content`.
 
 ### The Agent seam
@@ -51,14 +51,14 @@ The `run` is the one object you work with for the whole task. Three things you d
 
 | Call | Description |
 |------|-------------|
-| `run.client.open(protocol)` | Open a managed [capability](/v6/core/capabilities) client (shell, browser, ...) to act through. |
+| `run.client.open(protocol)` | Open a managed [capability](/v6/reference/capabilities) client (shell, browser, ...) to act through. |
 | `run.client.binding(protocol)` | Get a capability's raw wire address, to hand to an external SDK. |
 
-**Record the result** - `run.trace` is the [`Trace`](/v6/core/types#trace) you fill.
+**Record the result** - `run.trace` is the [`Trace`](/v6/reference/types#trace) you fill.
 
 | Call | Description |
 |------|-------------|
-| `run.record(step)` | Append a step and stream it to the platform live (step types in [Types](/v6/core/types)). |
+| `run.record(step)` | Append a step and stream it to the platform live (step types in [Types](/v6/reference/types)). |
 | `run.trace.content = ...` | Set the final answer, graded when the run ends. |
 
 ### Reusing HUD's loop: `ToolAgent`
@@ -73,7 +73,7 @@ There are two base classes, depending on how much of HUD's loop you want:
   recording.
 
 Record the step family that matches what happened - `AgentStep` (a model turn), `ToolStep` (a tool
-round-trip), or `SubagentStep` (a nested rollout); see [Types](/v6/core/types). `ToolAgent` does all of
+round-trip), or `SubagentStep` (a nested rollout); see [Types](/v6/reference/types). `ToolAgent` does all of
 this for you.
 
 ### Wrap an existing framework: browser-use on `cdp`
@@ -110,7 +110,7 @@ agent = OpenAIChatAgent(OpenAIChatConfig(
 
 ## Composing richer environments
 
-These patterns build on [Environments](/v6/core/environment) once the basics are in place.
+These patterns build on [Environments](/v6/reference/environment) once the basics are in place.
 
 ### Multiple capabilities at once
 
@@ -175,7 +175,7 @@ tasks = [fix_bug(difficulty=d) for d in range(1, 6)]
 ```
 
 A controlled difficulty distribution is what makes a taskset trainable - see
-[Designing tasks](/v6/core/advice).
+[Designing tasks](/v6/reference/advice).
 
 ### Structure a large taskset across files
 
@@ -214,7 +214,7 @@ rewards = [run.reward for run in job.runs]
 
 ### Route tasks to different substrates
 
-A [runtime](/v6/core/runtime) is called once per rollout with the task row, so a callable can place
+A [runtime](/v6/reference/runtime) is called once per rollout with the task row, so a callable can place
 heavier rows on heavier substrates:
 
 ```python run.py
@@ -281,7 +281,7 @@ env = Environment(
 Run the FastMCP server alongside the environment so the URL is live - for local iteration,
 `tools.run(transport="http", host="127.0.0.1", port=8080)`; in a built image, start it from your
 container entrypoint or an
-[`@env.initialize`](/v6/core/environment#lifecycle-hooks-set-up-and-tear-down) hook.
+[`@env.initialize`](/v6/reference/environment#lifecycle-hooks-set-up-and-tear-down) hook.
 
 ### How it looks to the orchestrator
 
@@ -299,7 +299,7 @@ the agent works against a multi-turn conversation. The `Chat` runner drives that
 turn and keeps the history for you.
 
 Reach for chat when the *interaction itself* is the thing - assistants, tool-use dialogues, anything
-where the agent needs prior turns. For evals and training, the default single-turn [task](/v6/core/tasks)
+where the agent needs prior turns. For evals and training, the default single-turn [task](/v6/reference/tasks)
 is what you want. Either way the grading model is the same: you still yield a reward.
 
 ### A chat-style task
@@ -377,8 +377,8 @@ For a complete A2A endpoint (sessions per context, agent card, citations transpo
 ## See also
 
 <CardGroup cols={2}>
-<Card title="Agents" icon="robot" href="/v6/core/agents" />
-<Card title="Capabilities" icon="plug" href="/v6/core/capabilities" />
-<Card title="Run & deploy" icon="rocket" href="/v6/core/runtime" />
+<Card title="Agents" icon="robot" href="/v6/reference/agents" />
+<Card title="Capabilities" icon="plug" href="/v6/reference/capabilities" />
+<Card title="Run & deploy" icon="rocket" href="/v6/reference/runtime" />
 <Card title="Harbor interop" icon="anchor" href="/v6/advanced/harbor-convert" />
 </CardGroup>
diff --git a/docs/v6/advanced/harbor-convert.mdx b/docs/v6/advanced/harbor-convert.mdx
index 67261acd..5ddb9f4f 100644
--- a/docs/v6/advanced/harbor-convert.mdx
+++ b/docs/v6/advanced/harbor-convert.mdx
@@ -84,13 +84,13 @@ set `[verifier.environment]` in `task.toml`.
 
 The mapping is mechanical, so **review the result** - confirm the prompt reads
 naturally, the grader scores what the prompt asks for, and there's no leftover
-answer leakage (see [Designing tasks for signal](/v6/core/advice)).
+answer leakage (see [Designing tasks for signal](/v6/reference/advice)).
 
 ## See also
 
 <CardGroup cols={2}>
-<Card title="Package & deploy" icon="rocket" href="/v6/core/runtime" />
-<Card title="Tasks & placement" icon="list-check" href="/v6/core/tasks" />
-<Card title="Designing tasks for signal" icon="signal" href="/v6/core/advice" />
-<Card title="CLI reference" icon="terminal" href="/v6/core/cli" />
+<Card title="Package & deploy" icon="rocket" href="/v6/reference/runtime" />
+<Card title="Tasks & placement" icon="list-check" href="/v6/reference/tasks" />
+<Card title="Designing tasks for signal" icon="signal" href="/v6/reference/advice" />
+<Card title="CLI reference" icon="terminal" href="/v6/reference/cli" />
 </CardGroup>
diff --git a/docs/v6/core/protocol.mdx b/docs/v6/advanced/protocol.mdx
similarity index 81%
rename from docs/v6/core/protocol.mdx
rename to docs/v6/advanced/protocol.mdx
index 71a410e3..1bd917a7 100644
--- a/docs/v6/core/protocol.mdx
+++ b/docs/v6/advanced/protocol.mdx
@@ -11,9 +11,9 @@ Three things take part in every run:
 
 | | What it is |
 |---|---|
-| [**Agent**](/v6/core/agents) | The *client* (a harness around a model). Drives the work - reads, acts, repeats. Any model, any framework. |
-| [**Environment**](/v6/core/environment) | The *server*. Holds the world, the tasks, and the grading. This is the part you author. |
-| [**Capabilities**](/v6/core/capabilities) | The live connections the agent acts through - `ssh`, `mcp`, `cdp`, `rfb`, `robot`. |
+| [**Agent**](/v6/reference/agents) | The *client* (a harness around a model). Drives the work - reads, acts, repeats. Any model, any framework. |
+| [**Environment**](/v6/reference/environment) | The *server*. Holds the world, the tasks, and the grading. This is the part you author. |
+| [**Capabilities**](/v6/reference/capabilities) | The live connections the agent acts through - `ssh`, `mcp`, `cdp`, `rfb`, `robot`. |
 
 ## The loop
 
@@ -40,7 +40,7 @@ The agent opens with a `hello`, and the environment answers with its **manifest*
 
 The orchestrator (the harness, `hud eval`, or the platform) names a task and calls `tasks.start`. The environment sets up the world for it and returns a **prompt**. The agent then works the task directly against the capabilities - a real shell over `ssh`, a real browser over `cdp` - reading observations and acting in a loop. The environment decides *what* the agent can touch, not *how* it works.
 
-When the agent is done it calls `tasks.grade`. The environment inspects the resulting state and returns one **reward**. That number, with the trace of the run, is the same value you read in an eval and feed into [training](/v6/core/training).
+When the agent is done it calls `tasks.grade`. The environment inspects the resulting state and returns one **reward**. That number, with the trace of the run, is the same value you read in an eval and feed into [training](/v6/reference/training).
 
 ## Two halves, one thin envelope
 
@@ -56,7 +56,7 @@ The loop has only two sides, with HUD between them:
 The envelope between them is tiny - a manifest, `tasks.start`, `tasks.grade` - so neither side needs to know anything about the other's internals. That separation is what makes an environment built today still run against a harness written years from now, with no environment-side glue.
 
 <Tip>
-In practice you rarely touch the agent side at all. The [HUD inference gateway](/v6/core/agents) lets you switch models by changing a single string - `"claude-sonnet-4-5"` to `"gpt-5"` - and nothing else. And when you *do* want full control, you can [bring your own harness](/v6/advanced/extending#bring-your-own-harness): it's a thin adapter, no protocol work.
+In practice you rarely touch the agent side at all. The [HUD inference gateway](/v6/reference/agents) lets you switch models by changing a single string - `"claude-sonnet-4-5"` to `"gpt-5"` - and nothing else. And when you *do* want full control, you can [bring your own harness](/v6/advanced/extending#bring-your-own-harness): it's a thin adapter, no protocol work.
 </Tip>
 
 ## The wire protocol
@@ -80,13 +80,13 @@ The held task survives a dropped connection, so a client can `tasks.start`, disc
 <Card title="Quickstart" icon="bolt" href="/v6/start/quickstart">
   From install to your first graded trace in a few minutes.
 </Card>
-<Card title="Capabilities" icon="plug" href="/v6/core/capabilities">
+<Card title="Capabilities" icon="plug" href="/v6/reference/capabilities">
   The connections an agent drives: shell, browser, GUI, tools, robot.
 </Card>
-<Card title="Tasks & tasksets" icon="list-check" href="/v6/core/tasks">
+<Card title="Tasks & tasksets" icon="list-check" href="/v6/reference/tasks">
   What `tasks.start` and `tasks.grade` operate on.
 </Card>
-<Card title="Agents" icon="robot" href="/v6/core/agents">
+<Card title="Agents" icon="robot" href="/v6/reference/agents">
   Swap the model with a string, or bring your own harness.
 </Card>
 </CardGroup>
diff --git a/docs/v6/advanced/robots.mdx b/docs/v6/advanced/robots.mdx
index a6608f71..46335146 100644
--- a/docs/v6/advanced/robots.mdx
+++ b/docs/v6/advanced/robots.mdx
@@ -490,5 +490,5 @@ downstream (`hud eval`, tasksets, the agent) is unchanged; only *where the bridg
 <Card title="Robot benchmark cookbook" icon="flask" href="/v6/cookbooks/robot-benchmark">
   LIBERO in Docker, driven by pi0.5, end to end.
 </Card>
-<Card title="Capabilities" icon="plug" href="/v6/core/capabilities" />
+<Card title="Capabilities" icon="plug" href="/v6/reference/capabilities" />
 </CardGroup>
diff --git a/docs/v6/build/overview.mdx b/docs/v6/build/overview.mdx
deleted file mode 100644
index 21178ab7..00000000
--- a/docs/v6/build/overview.mdx
+++ /dev/null
@@ -1,221 +0,0 @@
----
-title: "Overview"
-description: "How the HUD build workflow fits together: declare an environment, define tasks and capabilities, choose a runtime, run any agent, and learn."
-icon: "compass"
----
-
-## HUD
-
-[HUD](https://hud.ai) is a platform for building environments. You define an environment, write tasks for
-that environment, and run any agent to perform those tasks, at any scale. Our SDK is an
-[open-source](https://github.com/hud-evals/hud-python) Python framework for all of this.
-
-The full workflow flows in five steps:
-
-```mermaid
-flowchart LR
-    A(["1#160;·#160;Declare#160;your#160;environment"]) --> B(["2 · Choose your taskset"]) --> C(["3 · Choose your runtime"]) --> D(["4 · Run your agent"]) --> E(["5 · Learn"])
-    classDef s1 fill:#efece8,stroke:#2b2722,stroke-width:1px,color:#2b2722;
-    classDef s2 fill:#efece8,stroke:#2b2722,stroke-width:1px,color:#2b2722;
-    classDef s3 fill:#efece8,stroke:#2b2722,stroke-width:1px,color:#2b2722;
-    classDef s4 fill:#efece8,stroke:#2b2722,stroke-width:1px,color:#2b2722;
-    classDef s5 fill:#efece8,stroke:#2b2722,stroke-width:1px,color:#2b2722;
-    class A s1;
-    class B s2;
-    class C s3;
-    class D s4;
-    class E s5;
-```
-
-## Define any environment
-
-An environment is some closed container for your agent to act in. Fundamentally it's defined by:
-
-<div className="tight-list">
-
-- the **contents** of the container ([Environment](/v6/core/environment))
-- the **tasks** (and their rewards) to be performed inside it ([Tasks & Tasksets](/v6/core/tasks))
-- the **capabilities** the agent can use to perform these tasks ([Capabilities](/v6/core/capabilities))
-
-</div>
-
-The v6 SDK leverages modular abstractions for all of these, letting you build on or reuse existing parts.
-
-
-<Accordion title="Part 1: Declare your environment">
-
-The first and **key** part of any HUD workflow is **declaring your [environment](/v6/core/environment)**
-in a declaration file `env.py` - here is a standard scaffold:
-
-```python env.py
-from hud.environment import Environment
-from hud.capabilities import Capability
-from hud.graders import LLMJudgeGrader
-
-# VITAL: an env with at least one capability - this is what the agent connects to and drives
-env = Environment(name="...", capabilities=[
-    Capability.ssh(name="shell", url="<url>", host_pubkey="<key>"),  # a real shell over ssh
-])
-
-# OPTIONAL: lifecycle hooks - only if the task needs setup/teardown (fixtures, services, seed state)
-@env.initialize               # runs once before serving
-async def _up():
-    ...                       # write fixtures, stand up services, etc.
-
-@env.shutdown                 # runs on env.stop()
-async def _down():
-    ...
-
-# VITAL: at least one task definition - prompts the agent and returns a reward
-@env.template()               # one definition = a whole space of tasks
-async def some_task_1(...):
-    answer = yield "<prompt>"      # the prompt handed to the agent; the agent's answer comes back
-    # ── everything the agent does happens here: it drives the capability until it's done ──
-    result = await LLMJudgeGrader.grade(answer=answer, criteria=[...])   # score the result → reward
-    yield result.value           # VITAL: the final yield is the reward
-```
-
-This scaffold is general on purpose - it describes _any_ environment. A one-line shell task, a full GUI
-desktop, a robot simulator - they're all just environments with some bespoke **content**, **tasks**, and
-associated **capabilities**. The complexity hidden under this file is hidden in the
-[HUD protocol](/v6/core/protocol) Its thin envelope lets any model or harness plug into any environment.
-
-
-</Accordion>
-
-<Accordion title="Part 2: Choose your taskset">
-
-Then just form a [taskset](/v6/core/tasks) (one or more tasks with parameters) **in code** or load one
-**from a file**.
-
-```python tasks.py
-from hud.eval import Taskset
-from env import some_task_1, some_task_2
-
-# VITAL: a named taskset of concrete tasks to evaluate (parametrize one definition into many)
-TASKS = Taskset("my-taskset", [some_task_1(<args1>), some_task_1(<args2>), some_task_2(<args3>)])
-```
-
-
-</Accordion>
-
-## Spin it up anywhere
-
-Once defined, an environment shouldn't care where it runs - it should just work. The SDK lets you
-effortlessly switch between running your environment locally for development, on
-[Daytona](https://www.daytona.io/), [Modal](https://modal.com/), or [E2B](https://e2b.dev/) for scale,
-or [deploy to the HUD platform](/v6/core/runtime). The environment definition never changes - just the
-[Runtime](/v6/core/runtime) you pass:
-
-<Accordion title="Part 3: Choose your runtime">
-
-There are **two main ways** to run your declared environments.
-
-**1. [Package & deploy](/v6/core/runtime) to the platform.** Build a portable image once, push it to HUD,
-and run any tasks against it from the [platform](https://hud.ai) - compare models on a taskset and browse
-every trace, no local infra needed:
-
-```bash
-hud deploy                 # build + register your env image on HUD
-hud sync tasks my-taskset  # publish a taskset to run from the platform
-```
-
-**2. Run programmatically.** Drive rollouts programmatically from Python by picking a
-[runtime](/v6/core/runtime) - the same taskset runs against any of them:
-
-```python
-from hud.eval import LocalRuntime, DockerRuntime, ModalRuntime, HUDRuntime
-
-LocalRuntime("env.py")     # local child process - fastest iteration
-DockerRuntime("my-env")    # a fresh container per rollout
-ModalRuntime("my-env")     # a Modal cloud sandbox per rollout
-HUDRuntime()               # HUD's hosted infra (after `hud deploy`)
-```
-
-</Accordion>
-
-## Evaluate and train any AI agent inside it
-
-Since an environment only exposes capabilities, any agent plugs in. For standard models the
-[HUD inference gateway](/v6/core/agents) and our **prebuilt harnesses** let you switch between models like
-Claude, GPT, or Gemini just by choosing the model name.
-
-Run rollouts in parallel with full isolation out of the box. Every rollout in the job is traced on the
-[platform](https://hud.ai), so you can see exactly what the agent did realtime and how it was graded.
-
-<Accordion title="Part 4: Run your agent">
-
-You can run this programmatically:
-
-```python
-from hud.agents import create_agent
-from hud.eval import LocalRuntime
-from tasks import TASKS
-
-agent = create_agent("claude-sonnet-4-5")               # routed through the HUD gateway
-
-job = await TASKS.run(agent, runtime=LocalRuntime("env.py"))   # start the run
-print(job.reward)
-```
-{/*
-<Note>You need a `HUD_API_KEY` ([hud.ai](https://hud.ai/project/api-keys)) for the gateway and tracing, or a provider key (`ANTHROPIC_API_KEY`, …) to call a model directly. See [Run on any model](/v6/core/agents).</Note> */}
-
-
-
-or run it from the [CLI](/v6/core/cli):
-```bash
-hud eval env.py claude --group 3
-```
-
-
-</Accordion>
-
-<Accordion title="Part 5: Learn">
-
-The rewards can then be used for your [training](/v6/core/training): run a group per task and feed the
-spread straight into your own GRPO/PPO loop - or a stack like
-[Tinker](https://thinkingmachines.ai/tinker/), [slime](https://github.com/THUDM/slime), or
-[Fireworks](https://fireworks.ai/).
-
-</Accordion>
-
-{/* ## Core Principles of SDK
-
-A few beliefs shape everything in the SDK:
-
-<div className="principles">
-  <div className="principle">
-    **Environments should outlast the agents that run them.**
-    The systems an agent works on (a shell, a browser, a filesystem) have barely changed in a decade,
-    and the tasks built on them are just as stable.
-  </div>
-  <div className="principle">
-    **Tasks should be generative, not declarative.**
-    A task definition should be like a template and span a *space* of challenges - exactly
-    the structure a synthetic pipeline needs. An entire benchmark like SWE-bench or Terminal-Bench
-    can live as one generative task definition
-    One environment holds any number of tasks; there's no separate image per task.
-  </div>
-  <div className="principle">
-    **Everything except the environment and reward should be swappable.**
-    The model, the harness, the infra you run on - all yours to change.
-    HUD just hands the agent a direct connection to the environment (`ssh` for a shell, `cdp` for a browser, `rfb` for a screen, `robot` for a simulator) and returns a reward.
-  </div>
-</div> */}
-
-
-## Where to go next
-
-<Note>
-To see what HUD hides under the hood, read about the [Protocol](/v6/core/protocol). To go in depth on
-each part of the workflow, start with [Environments](/v6/core/environment).
-</Note>
-
-<CardGroup cols={2}>
-<Card title="Build" icon="hammer" href="/v6/core/environment">
-  A high-level guide on how to work with HUD.
-</Card>
-<Card title="Reference" icon="brackets-curly" href="/v6/core/environment">
-  The actual object reference: classes, objects, and abstractions.
-</Card>
-</CardGroup>
diff --git a/docs/v6/cookbooks/coding-agent.mdx b/docs/v6/cookbooks/coding-agent.mdx
index 12b37832..5fb1c29c 100644
--- a/docs/v6/cookbooks/coding-agent.mdx
+++ b/docs/v6/cookbooks/coding-agent.mdx
@@ -49,7 +49,7 @@ tasks = [fix_add()]
 This task has no `answer = yield` - the deliverable is the **state of the workspace**, not a text answer.
 
 <Note>
-To start from an existing repo instead of seeding files inline, write it into the workspace root in `@env.initialize`, or pass `mounts=` (see [Capabilities](/v6/core/capabilities)).
+To start from an existing repo instead of seeding files inline, write it into the workspace root in `@env.initialize`, or pass `mounts=` (see [Capabilities](/v6/reference/capabilities)).
 </Note>
 
 ## Run it
@@ -97,8 +97,8 @@ tasks = [fix_add(target=t) for t in ("test_calc.py", "test_utils.py", "test_io.p
 ## See also
 
 <CardGroup cols={2}>
-<Card title="Environment reference" icon="cube" href="/v6/core/environment" />
-<Card title="Graders" icon="scale-balanced" href="/v6/core/graders" />
-<Card title="Designing tasks for signal" icon="signal" href="/v6/core/advice" />
+<Card title="Environment reference" icon="cube" href="/v6/reference/environment" />
+<Card title="Graders" icon="scale-balanced" href="/v6/reference/graders" />
+<Card title="Designing tasks for signal" icon="signal" href="/v6/reference/advice" />
 <Card title="Ops diagnostics" icon="stethoscope" href="/v6/cookbooks/ops-diagnostics" />
 </CardGroup>
diff --git a/docs/v6/cookbooks/ops-diagnostics.mdx b/docs/v6/cookbooks/ops-diagnostics.mdx
index ad5e7e1a..6236b454 100644
--- a/docs/v6/cookbooks/ops-diagnostics.mdx
+++ b/docs/v6/cookbooks/ops-diagnostics.mdx
@@ -60,7 +60,7 @@ The answer is the agent's **text diagnosis** (`answer = yield ...`). The judge s
 
 ## Why this is a good training task
 
-It satisfies the [signal](/v6/core/advice) principles:
+It satisfies the [signal](/v6/reference/advice) principles:
 
 - **Multi-channel integration** - the cause (a removed index) is in `deploy.log`, but the symptom path runs through `db.log` and `api.log`. No single file is decisive, so the agent must *integrate*.
 - **Multi-step** - the agent reads several files, forms a hypothesis, and checks it against the evidence.
@@ -77,13 +77,13 @@ Inspect the trace at [hud.ai](https://hud.ai) to see which files the agent read
 
 ## Build a spread
 
-Vary the incident to mint a dataset with a difficulty range - some with an obvious deploy cause, some where the evidence is more scattered. A controlled difficulty distribution is what makes the set trainable (see [Designing tasks for signal](/v6/core/advice)).
+Vary the incident to mint a dataset with a difficulty range - some with an obvious deploy cause, some where the evidence is more scattered. A controlled difficulty distribution is what makes the set trainable (see [Designing tasks for signal](/v6/reference/advice)).
 
 ## See also
 
 <CardGroup cols={2}>
-<Card title="Designing tasks for signal" icon="signal" href="/v6/core/advice" />
-<Card title="Graders" icon="scale-balanced" href="/v6/core/graders" />
+<Card title="Designing tasks for signal" icon="signal" href="/v6/reference/advice" />
+<Card title="Graders" icon="scale-balanced" href="/v6/reference/graders" />
 <Card title="Coding agent" icon="code" href="/v6/cookbooks/coding-agent" />
-<Card title="Train on rewards" icon="dumbbell" href="/v6/core/training" />
+<Card title="Train on rewards" icon="dumbbell" href="/v6/reference/training" />
 </CardGroup>
diff --git a/docs/v6/cookbooks/robot-benchmark.mdx b/docs/v6/cookbooks/robot-benchmark.mdx
index 7d51dc84..9760bb3b 100644
--- a/docs/v6/cookbooks/robot-benchmark.mdx
+++ b/docs/v6/cookbooks/robot-benchmark.mdx
@@ -123,5 +123,5 @@ With `HUD_API_KEY` set, every episode streams to the platform automatically: the
 <Card title="Robots reference" icon="robot" href="/v6/advanced/robots">
   Contracts, bridges, sim threading, and the harness API.
 </Card>
-<Card title="Package & deploy" icon="rocket" href="/v6/core/runtime" />
+<Card title="Package & deploy" icon="rocket" href="/v6/reference/runtime" />
 </CardGroup>
diff --git a/docs/v6/core/cli.mdx b/docs/v6/core/cli.mdx
deleted file mode 100644
index 4aa276c2..00000000
--- a/docs/v6/core/cli.mdx
+++ /dev/null
@@ -1,182 +0,0 @@
----
-title: "CLI"
-description: "Reference for the hud CLI across the environment lifecycle: init, serve, build, push, sync, eval, deploy, models, and the platform login commands."
-icon: "terminal"
----
-
-Install the CLI with `uv tool install hud-python --python 3.12`. Authenticate once with `hud set HUD_API_KEY=...`.
-
-## Build & iterate
-
-### `hud init`
-
-Scaffold a new environment package in a fresh `<name>` directory. With no preset it writes a minimal local scaffold - `env.py` (environment, templates, capabilities), `tasks.py` (concrete task rows), `Dockerfile.hud`, and `pyproject.toml` - no network, no API key. With `--preset` (or the interactive picker in a TTY) it downloads a starter environment from GitHub instead.
-
-```bash
-hud init                          # pick a template → ./<template>
-hud init my-env                   # pick a template (or minimal scaffold) → ./my-env
-hud init my-env --preset browser  # download the "browser" starter into ./my-env
-hud init --preset cua             # download the "cua" starter into ./cua-template
-hud init my-env --dir envs        # create ./envs/my-env
-```
-
-| Option | Description |
-|--------|-------------|
-| `--preset`, `-p` | Starter to download: `blank`, `browser`, `cua`, `deepresearch`, `coding`, `ml`, `ml-triage`, `verilog`, `autonomous-businesses`, `gdpval`, `worldsim`, `videogamebench`. Omit for the interactive picker (TTY); with a `NAME` in a non-interactive shell, omitting it writes the minimal local scaffold. |
-| `--dir`, `-d` | Parent directory (default `.`). |
-| `--force`, `-f` | Overwrite existing files. |
-
-### `hud serve`
-
-Serve an environment's control channel locally (tcp JSON-RPC). `hud dev` is a
-deprecated alias.
-
-```bash
-hud serve               # auto-detect env.py
-hud serve env:env       # explicit module:attribute
-hud serve env.py -p 9000
-```
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `--port`, `-p` | `8765` | Port to serve on. |
-| `--host` | `127.0.0.1` | Interface to bind (use `0.0.0.0` inside containers). |
-| `--verbose`, `-v` | - | Detailed logs. |
-
-### `hud deploy`
-
-Build **and** publish to HUD infra in one step. The environment's name comes
-from the `Environment(...)` declaration in code; deploying the same name again
-rebuilds that environment.
-
-```bash
-hud deploy
-```
-
-| Option | Description |
-|--------|-------------|
-| `--all`, `-a` | Deploy all environments in the directory. |
-| `--env`, `-e` | Env var `KEY=VALUE` (repeatable). |
-| `--env-file` | Path to a `.env` file. |
-
-## Evaluate
-
-### `hud eval`
-
-The primary local iteration loop: run an agent over a task source (`.py`, directory, or JSON/JSONL), grade the result, and print the reward. Each rollout gets a **fresh subprocess** for the env - no shared state between tasks.
-
-```bash
-# Split layout (hud init): templates in env.py, task rows in tasks.py
-hud eval tasks.py claude
-hud eval tasks.py claude --full --group 3
-
-# Single-file layout: env + tasks list in one file
-hud eval env.py claude
-hud eval env.py claude --model claude-haiku-4-5   # cheaper model for fast iteration
-hud eval env.py claude --max-steps 30
-hud eval env.py claude --all                      # every task, not just the first
-hud eval env.py claude --full                     # every task, auto-respond, 100 steps
-```
-
-<Note>
-`hud eval` loads tasks from the path you pass. In a split project, point it at `tasks.py` (or `.` to scan the directory). It spawns `env.py` for the control channel automatically - you don't pass both files.
-</Note>
-
-**What you don't need for a local run:**
-- A HUD API key - local evals don't hit the platform
-- `hud serve` running - `hud eval` spawns the env subprocess for you
-- Docker - unless your env explicitly uses `DockerRuntime`
-- An SSH connection - the gateway timeout only applies when `env.workspace()` is declared
-
-For a platform taskset, pass its name or id directly: `hud eval "My Tasks" claude`. The tasks are fetched from the platform and the rollouts run remotely by default, since the env source is not on disk.
-
-**Single-task runs** show step-by-step progress (step number + tool calls). Multi-task batches are silent unless `--verbose` is passed.
-
-| Option | Description |
-|--------|-------------|
-| `--full` | Run the whole dataset (`--all --auto-respond --max-steps 100`). |
-| `--all` | Run every task instead of just the first. |
-| `--model`, `-m` | Model id. |
-| `--gateway`, `-g` | Force LLM calls through the HUD gateway. Implied when only `HUD_API_KEY` is set (no provider key); pass it to force the gateway when a provider key is also present. |
-| `--group` (alias `--group-size`) | Runs per task - a group of repeats whose reward spread you can inspect. |
-| `--max-concurrent` | Cap parallel rollouts. |
-| `--max-steps` | Cap steps per task (default 10). |
-| `--task-ids` | Comma-separated slugs or 0-based indices. |
-| `--config`, `-c` | Agent config `key=value` (repeatable). |
-| `--verbose`, `-v` | Show agent logs (step progress, tool calls) for batch runs too. |
-| `--very-verbose`, `-vv` | Debug-level logs. |
-| `--runtime` | Placement: `local`, `hud` (HUD runtime tunnel), or `tcp://host:port`. Defaults to `local` for a tasks file; platform tasksets default to remote hosted execution. |
-| `--remote` | Run the whole rollout remotely on the HUD platform. |
-| `--yes`, `-y` | Skip confirmation prompt. |
-
-## Run a packaged image
-
-`hud task start` / `hud task grade` attach to an env already serving locally (e.g. inside a built image, or alongside `hud serve`), or load one from source with `--source`. `hud task list` always reads from source (default `.`) - it doesn't attach.
-
-```bash
-hud task list                          # what tasks are exposed
-hud task start fix_bug                 # -> the prompt (stdout)
-hud task grade fix_bug --answer "..."  # -> the reward (stdout)
-```
-
-| Command | Key options |
-|---------|-------------|
-| `hud task start <task>` | `--source`/`-s`, `--args` (JSON), `--url`/`-u`, `--out`/`-o` |
-| `hud task grade <task>` | `--answer`, `--answer-file`, `--source`, `--args`, `--url`, `--out` |
-| `hud task list` | `--source`/`-s` |
-
-## Platform
-
-```bash
-hud sync tasks my-taskset      # publish tasks as a named taskset
-hud sync env                   # sync environment metadata
-```
-
-External benchmark formats (currently Harbor) load directly into the runtime
-as `Taskset`s - no conversion step. See [Harbor interop](/v6/advanced/harbor-convert).
-
-## Inspect
-
-### `hud jobs [<id>]`
-
-Without an id, lists your most recent jobs. With an id, lists every trace in that job.
-
-```bash
-hud jobs               # recent jobs - id, name, taskset, status, created
-hud jobs <job-id>      # traces for one job - trace id, status, reward, error
-hud jobs --json        # raw JSON
-hud jobs -n 50         # show up to 50 rows (default 20)
-```
-
-### `hud trace <trace_id>`
-
-Inspect a single rollout. Reads from the local telemetry JSONL file first
-(`HUD_TELEMETRY_LOCAL_DIR/<trace_id>.jsonl`) and falls back to the platform API.
-
-```bash
-hud trace <trace-id>          # rendered view: agent turns, tool calls, tool results
-hud trace <trace-id> --json   # raw event list
-```
-
-Set `HUD_TELEMETRY_LOCAL_DIR` in your environment to write spans to disk during a
-rollout so `hud trace` can read them offline without an API call.
-
-## Other commands
-
-| Command | Description |
-|---------|-------------|
-| `hud set KEY=VALUE` | Persist credentials/vars to `~/.hud/.env`. |
-| `hud login` | Authenticate with HUD. |
-| `hud models list` | List gateway models. |
-| `hud models fork <model> --name <slug>` | Fork a trainable model from an existing one. |
-| `hud models checkpoints <model>` | List a model's checkpoint tree. |
-| `hud models head <model> [--set <checkpoint-id>]` | Show - or set (rollback/select) - a model's active checkpoint. |
-| `hud cancel` | Cancel a running job. |
-| `hud version` | Show the CLI version. |
-
-## See also
-
-<CardGroup cols={2}>
-<Card title="Quickstart" icon="bolt" href="/v6/start/quickstart" />
-<Card title="Run & deploy" icon="rocket" href="/v6/core/runtime" />
-</CardGroup>
diff --git a/docs/v6/more/faq.mdx b/docs/v6/more/faq.mdx
index e6c38c76..f23cbadc 100644
--- a/docs/v6/more/faq.mdx
+++ b/docs/v6/more/faq.mdx
@@ -24,7 +24,7 @@ You write the environment once; the model, harness, trainer, and infra all stay
 
 <AccordionGroup>
 <Accordion title="Do I need Docker?">
-Not for the quickstart. `hud eval`, `hud serve`, and gateway runs need **no Docker** - you write a `tasks.py` and run it. You only need Docker for the **packaging path**: building a portable image from `Dockerfile.hud` and the build step of `hud deploy`. See [Package & deploy](/v6/core/runtime).
+Not for the quickstart. `hud eval`, `hud serve`, and gateway runs need **no Docker** - you write a `tasks.py` and run it. You only need Docker for the **packaging path**: building a portable image from `Dockerfile.hud` and the build step of `hud deploy`. See [Package & deploy](/v6/reference/runtime).
 </Accordion>
 
 <Accordion title="Do I need an API key?">
@@ -32,11 +32,11 @@ You need **one** of:
 - A **`HUD_API_KEY`** ([hud.ai/project/api-keys](https://hud.ai/project/api-keys)) - routes models through the HUD gateway (the default when no provider key is set) and traces every rollout. One key for everything.
 - A **provider key** (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`) - to call that provider directly instead of the gateway.
 
-See [Run on any model](/v6/core/agents).
+See [Run on any model](/v6/reference/agents).
 </Accordion>
 
 <Accordion title="Do I need a GPU?">
-No - not to build environments, write tasks, or run evals. Inference happens through the gateway or your provider. **Training** feeds HUD's rewards into your own GRPO/PPO loop (or a stack like Tinker, slime, or Fireworks), which brings its own compute. See [Train on rewards](/v6/core/training).
+No - not to build environments, write tasks, or run evals. Inference happens through the gateway or your provider. **Training** feeds HUD's rewards into your own GRPO/PPO loop (or a stack like Tinker, slime, or Fireworks), which brings its own compute. See [Train on rewards](/v6/reference/training).
 </Accordion>
 
 <Accordion title="My environment imports a package hud can't find - why?">
@@ -49,7 +49,7 @@ uv run hud eval tasks.py claude
 </Accordion>
 
 <Accordion title="What platforms are supported (macOS / Windows / Linux)?">
-The CLI and SDK run on macOS, Windows, and Linux. Two caveats: `ssh` sandbox isolation is **Linux-only** (the shell still runs without it elsewhere), and `BashGrader` needs bash, so on native Windows it scores `0.0`. Both are fine for local iteration and resolved inside a built Linux image. See [Capabilities](/v6/core/capabilities).
+The CLI and SDK run on macOS, Windows, and Linux. Two caveats: `ssh` sandbox isolation is **Linux-only** (the shell still runs without it elsewhere), and `BashGrader` needs bash, so on native Windows it scores `0.0`. Both are fine for local iteration and resolved inside a built Linux image. See [Capabilities](/v6/reference/capabilities).
 </Accordion>
 </AccordionGroup>
 
@@ -73,10 +73,10 @@ Running locally with your own provider key (`hud serve`, `hud eval ... claude`)
 
 <AccordionGroup>
 <Accordion title="Environment vs task vs taskset?">
-- **Environment** - where the agent acts; exposes [capabilities](/v6/core/capabilities) (`ssh`, `cdp`, …).
+- **Environment** - where the agent acts; exposes [capabilities](/v6/reference/capabilities) (`ssh`, `cdp`, …).
 - **Task definition** - a `@env.template` async generator that prompts and grades.
 - **Task** - calling a definition (`count_letter(word="…")`) mints one runnable, parameterized data row.
-- **Taskset** - a collection of tasks you evaluate one agent over, with optional GRPO grouping. See [Tasks & tasksets](/v6/core/tasks).
+- **Taskset** - a collection of tasks you evaluate one agent over, with optional GRPO grouping. See [Tasks & tasksets](/v6/reference/tasks).
 </Accordion>
 
 <Accordion title="hud eval vs hud serve vs hud deploy - which when?">
@@ -84,19 +84,19 @@ Running locally with your own provider key (`hud serve`, `hud eval ... claude`)
 - **`hud serve env.py`** - serve the environment locally so you can drive one task by hand (`hud task start` / `hud task grade`).
 - **`hud deploy`** - build a portable Docker image **and** publish to HUD infra in one step.
 
-Full surface in the [CLI reference](/v6/core/cli).
+Full surface in the [CLI reference](/v6/reference/cli).
 </Accordion>
 
 <Accordion title="hud eval env.py or tasks.py?">
-Pass the file that **lists runnable tasks**. In the split layout (`hud init`) that's `tasks.py` (it imports templates from `env.py`); in a single-file setup it's whatever file holds both the `Environment` and the `tasks = [...]` list. The CLI spawns `env.py` for the control channel automatically - you don't pass both. Point it at `.` to scan a directory. See the [CLI reference](/v6/core/cli).
+Pass the file that **lists runnable tasks**. In the split layout (`hud init`) that's `tasks.py` (it imports templates from `env.py`); in a single-file setup it's whatever file holds both the `Environment` and the `tasks = [...]` list. The CLI spawns `env.py` for the control channel automatically - you don't pass both. Point it at `.` to scan a directory. See the [CLI reference](/v6/reference/cli).
 </Accordion>
 
 <Accordion title="Can I use my own model or a local endpoint?">
-Yes. `OpenAIChatAgent` speaks the OpenAI Chat Completions API, so any compatible server (vLLM, a local model, a hosted checkpoint) works - point `base_url` at it. From the CLI use the `openai_compatible` agent. See [Run on any model](/v6/core/agents) and [Integrations](/v6/advanced/extending).
+Yes. `OpenAIChatAgent` speaks the OpenAI Chat Completions API, so any compatible server (vLLM, a local model, a hosted checkpoint) works - point `base_url` at it. From the CLI use the `openai_compatible` agent. See [Run on any model](/v6/reference/agents) and [Integrations](/v6/advanced/extending).
 </Accordion>
 
 <Accordion title="Do I have to train, or can I just run evals?">
-Evals are a complete use on their own - write tasks, run them across models, read rewards and traces. Training is **optional**: because every rollout returns a reward and a trace, the same tasks become training data **if and when** you want them to. See [Train on rewards](/v6/core/training).
+Evals are a complete use on their own - write tasks, run them across models, read rewards and traces. Training is **optional**: because every rollout returns a reward and a trace, the same tasks become training data **if and when** you want them to. See [Train on rewards](/v6/reference/training).
 </Accordion>
 
 <Accordion title="Can I bring an existing benchmark or tasks?">
@@ -118,7 +118,7 @@ Scenarios became tasks, registered tools became capabilities, and the env serves
 <Card title="Quickstart" icon="bolt" href="/v6/start/quickstart">
   Zero to a first graded trace.
 </Card>
-<Card title="Designing tasks for signal" icon="signal" href="/v6/core/advice">
+<Card title="Designing tasks for signal" icon="signal" href="/v6/reference/advice">
   What makes a task actually worth training on.
 </Card>
 </CardGroup>
diff --git a/docs/v6/more/migrate-v6.mdx b/docs/v6/more/migrate-v6.mdx
index 2be550ab..96310760 100644
--- a/docs/v6/more/migrate-v6.mdx
+++ b/docs/v6/more/migrate-v6.mdx
@@ -119,7 +119,7 @@ v5 served an MCP server via `env.run(transport=...)`. v6 serves its control chan
 
 ## Converting with an agent
 
-The conversion is mechanical, so the fastest path is to let your coding agent do it. Add the HUD docs to your agent - they're available as an MCP server at `docs.hud.ai/mcp`, or use the **Copy / Claude / ChatGPT** buttons at the top of any docs page - then point it at this guide and the [Environment reference](/v6/core/environment) and ask it to adapt your `env.py`. A prompt like:
+The conversion is mechanical, so the fastest path is to let your coding agent do it. Add the HUD docs to your agent - they're available as an MCP server at `docs.hud.ai/mcp`, or use the **Copy / Claude / ChatGPT** buttons at the top of any docs page - then point it at this guide and the [Environment reference](/v6/reference/environment) and ask it to adapt your `env.py`. A prompt like:
 
 > Convert this v5 HUD environment to v6 using the migration guide at docs.hud.ai. Rename scenarios to tasks, replace registered tools with the capability they imply (shell/files → `ssh`, browser → `cdp`, computer-use → `rfb`, custom tools → `mcp`), switch `env("name", ...)` to calling the task, and fix the `hud.tools` imports below.
 
@@ -149,13 +149,13 @@ The rule of thumb: **grading types move to `hud.graders`, tools become capabilit
 ## Next steps
 
 <CardGroup cols={2}>
-<Card title="Environment reference" icon="cube" href="/v6/core/environment">
+<Card title="Environment reference" icon="cube" href="/v6/reference/environment">
   Define capabilities, lifecycle hooks, and tasks.
 </Card>
-<Card title="Tasks & Tasksets" icon="list-check" href="/v6/core/tasks">
+<Card title="Tasks & Tasksets" icon="list-check" href="/v6/reference/tasks">
   Define tasks, collect tasksets, and grade runs.
 </Card>
-<Card title="Package & deploy" icon="rocket" href="/v6/core/runtime">
+<Card title="Package & deploy" icon="rocket" href="/v6/reference/runtime">
   Publish with hud deploy and run at scale.
 </Card>
 </CardGroup>
diff --git a/docs/v6/core/advice.mdx b/docs/v6/reference/advice.mdx
similarity index 95%
rename from docs/v6/core/advice.mdx
rename to docs/v6/reference/advice.mdx
index de740035..4c9a802f 100644
--- a/docs/v6/core/advice.mdx
+++ b/docs/v6/reference/advice.mdx
@@ -67,7 +67,7 @@ shape alone.
 A task where one inference call produces the deliverable doesn't give RL enough rollout structure to
 learn from. Real training tasks require **multiple steps** - several observations, tool calls, or turns
 - so the trajectory carries learnable structure. If your task is single-shot, give the agent something
-to *do*: a [capability](/v6/core/environment) to act through and a problem that requires integrating
+to *do*: a [capability](/v6/reference/environment) to act through and a problem that requires integrating
 evidence across more than one observation.
 
 ## Keep the answer out of the environment
@@ -93,7 +93,7 @@ What the prompt sets up, the grader should test - and vice versa. Two related pr
   If a generic memo that did no investigation can outscore a thorough one, the grader is measuring
   shape, not substance.
 
-Compose graders so a partial reward is legible (see [`combine`](/v6/core/graders)) - subscores let you
+Compose graders so a partial reward is legible (see [`combine`](/v6/reference/graders)) - subscores let you
 see which component earned the reward, which is how you catch monotonicity violations.
 
 ## Source substrate that isn't memorized
@@ -134,8 +134,8 @@ costume - same operation, different proper nouns - won't train general capabilit
 ## See also
 
 <CardGroup cols={2}>
-<Card title="Tasks & Tasksets" icon="list-check" href="/v6/core/tasks" />
-<Card title="Graders" icon="scale-balanced" href="/v6/core/graders" />
-<Card title="Training" icon="dumbbell" href="/v6/core/training" />
+<Card title="Tasks & Tasksets" icon="list-check" href="/v6/reference/tasks" />
+<Card title="Graders" icon="scale-balanced" href="/v6/reference/graders" />
+<Card title="Training" icon="dumbbell" href="/v6/reference/training" />
 <Card title="Composing richer environments" icon="puzzle-piece" href="/v6/advanced/extending" />
 </CardGroup>
diff --git a/docs/v6/core/agents.mdx b/docs/v6/reference/agents.mdx
similarity index 89%
rename from docs/v6/core/agents.mdx
rename to docs/v6/reference/agents.mdx
index f7553f12..3dd4fcb5 100644
--- a/docs/v6/core/agents.mdx
+++ b/docs/v6/reference/agents.mdx
@@ -5,8 +5,8 @@ icon: "robot"
 mode: "wide"
 ---
 
-An **agent** is what acts inside an [environment](/v6/core/environment): it works a
-[task](/v6/core/tasks) through the environment's [capabilities](/v6/core/capabilities) and produces the
+An **agent** is what acts inside an [environment](/v6/reference/environment): it works a
+[task](/v6/reference/tasks) through the environment's [capabilities](/v6/reference/capabilities) and produces the
 answer that gets graded. Concretely it's a **model** wrapped in a **harness** - the loop that feeds the
 model observations and turns its output into actions. In the framework an agent is anything callable as
 `await agent(run)`, where the `run` is the live handle for one task: its prompt, its connection to the
@@ -70,7 +70,7 @@ CLI over an `ssh` capability, against the env's filesystem. Every knob (`model`,
 
 Run a task with an agent two ways.
 
-**Programmatically** - pass the agent to `task.run` / `taskset.run` with a [runtime](/v6/core/runtime):
+**Programmatically** - pass the agent to `task.run` / `taskset.run` with a [runtime](/v6/reference/runtime):
 
 ```python
 from hud.agents import create_agent
@@ -82,7 +82,7 @@ job = await TASKS.run(agent, runtime=LocalRuntime("env.py"))
 print(job.reward)
 ```
 
-**From the [CLI](/v6/core/cli#hud-eval)** - `hud eval` takes a task source (`.py`, a directory, or
+**From the [CLI](/v6/reference/cli#hud-eval)** - `hud eval` takes a task source (`.py`, a directory, or
 `.json`/`.jsonl`) and an agent name (`claude`, `openai`, `gemini`, `openai_compatible`), runs each
 rollout in a fresh env subprocess, grades it, and prints the reward:
 
@@ -103,7 +103,7 @@ Flags override the agent's config for that run:
 | `--gateway` | Force calls through the gateway even when a provider key is set. |
 
 With only a `HUD_API_KEY` set, calls route through the gateway; with a provider key present they go
-straight to the provider. See the [CLI reference](/v6/core/cli#hud-eval) for the full flag set and key
+straight to the provider. See the [CLI reference](/v6/reference/cli#hud-eval) for the full flag set and key
 resolution.
 
 ## Bring your own harness
@@ -117,7 +117,7 @@ the seam, the `Run` object you work with, the step types you record, and worked
 
 <CardGroup cols={2}>
 <Card title="Bring your own harness" icon="screwdriver-wrench" href="/v6/advanced/extending#bring-your-own-harness" />
-<Card title="Capabilities" icon="plug" href="/v6/core/capabilities" />
-<Card title="Types: Run & Trace" icon="code" href="/v6/core/types" />
+<Card title="Capabilities" icon="plug" href="/v6/reference/capabilities" />
+<Card title="Types: Run & Trace" icon="code" href="/v6/reference/types" />
 <Card title="Robots (beta)" icon="robot" href="/v6/advanced/robots" />
 </CardGroup>
diff --git a/docs/v6/core/capabilities.mdx b/docs/v6/reference/capabilities.mdx
similarity index 97%
rename from docs/v6/core/capabilities.mdx
rename to docs/v6/reference/capabilities.mdx
index f0b8a047..c57a6809 100644
--- a/docs/v6/core/capabilities.mdx
+++ b/docs/v6/reference/capabilities.mdx
@@ -256,7 +256,7 @@ Spinning up a capability is the environment side. The harness side is the mirror
 | `RFBClient` | `rfb/3.8` |
 | `RobotClient` | `openpi/0` - joins the registry on first open (the `robot` extra: numpy/openpi-client) |
 
-The bundled provider agents open these automatically based on which capabilities the manifest advertises (see [Agents](/v6/core/agents)). To write your own harness, attach to the capability you need and define your tool spec.
+The bundled provider agents open these automatically based on which capabilities the manifest advertises (see [Agents](/v6/reference/agents)). To write your own harness, attach to the capability you need and define your tool spec.
 
 ## Workspace
 
@@ -295,7 +295,7 @@ To run one outside an env, drive its lifecycle directly and publish `ws.capabili
 ## See also
 
 <CardGroup cols={2}>
-<Card title="Environment" icon="cube" href="/v6/core/environment" />
-<Card title="Agents" icon="robot" href="/v6/core/agents" />
-<Card title="Tasks & Tasksets" icon="list-check" href="/v6/core/tasks" />
+<Card title="Environment" icon="cube" href="/v6/reference/environment" />
+<Card title="Agents" icon="robot" href="/v6/reference/agents" />
+<Card title="Tasks & Tasksets" icon="list-check" href="/v6/reference/tasks" />
 </CardGroup>
diff --git a/docs/v6/core/environment.mdx b/docs/v6/reference/environment.mdx
similarity index 91%
rename from docs/v6/core/environment.mdx
rename to docs/v6/reference/environment.mdx
index 116a08cf..932841f1 100644
--- a/docs/v6/core/environment.mdx
+++ b/docs/v6/reference/environment.mdx
@@ -47,7 +47,7 @@ async def my_task(...):
 When you serve, HUD imports the module, finds the `Environment` object in it, and runs everything
 registered on it. The only contract is "this module defines an `Environment`", which is what makes
 the declaration portable: the same `env.py` runs locally, in a container, or on HUD with nothing
-changed but the [runtime](/v6/core/runtime).
+changed but the [runtime](/v6/reference/runtime).
 
 ### Capabilities: the access you expose
 
@@ -75,7 +75,7 @@ You register capabilities three ways: in the **constructor** for a service that
 `ssh` capability in the scaffold above), with **`env.workspace(root)`** for the common shell case, or
 with **`env.add_capability(...)`** from a hook for a daemon the env runs itself (next section). Each
 is concrete wire data - the URL of something serving the protocol. Every protocol has a
-copy-pasteable spin-up in the [Capabilities](/v6/core/capabilities) reference, with the library that
+copy-pasteable spin-up in the [Capabilities](/v6/reference/capabilities) reference, with the library that
 backs it.
 
 ### Lifecycle hooks: set up and tear down
@@ -104,7 +104,7 @@ async def _down():
 This is also how you publish a daemon you run yourself: start it, then `env.add_capability(...)`.
 It replaces any same-named entry, so re-serving overwrites a stale address rather than duplicating
 it. The full pattern - starting a server task and blocking until it binds - lives in
-[Capabilities](/v6/core/capabilities#spinning-up-a-capability).
+[Capabilities](/v6/reference/capabilities#spinning-up-a-capability).
 
 ### Tasks: a prompt and a reward
 
@@ -123,7 +123,7 @@ async def count_letter(word: str = "strawberry", letter: str = "r"):
 
 A template is generative, not a single task: its parameters (`word`, `letter`) fill in per run, so
 one definition describes a whole *space* of tasks. Calling it - `count_letter(word="raspberry")` -
-binds those arguments and mints one concrete [`Task`](/v6/core/tasks) you can run. Register as many
+binds those arguments and mints one concrete [`Task`](/v6/reference/tasks) you can run. Register as many
 templates as you like on one environment; each is advertised in the manifest, so a harness can
 discover what the environment offers and the orchestrator can pick which to run.
 
@@ -134,15 +134,15 @@ discover what the environment offers and the orchestrator can pick which to run.
 | `id` | `str \| None` | Task id (defaults to the function name). |
 | `description` | `str` | Human-readable description, surfaced in the manifest. |
 | `input` | `Any` | Optional type for the agent's input (JSON schema in the manifest). |
-| `returns` | `Any` | Optional type the agent must produce; the answer arrives as an `Answer[T]`. See [Types](/v6/core/types). |
+| `returns` | `Any` | Optional type the agent must produce; the answer arrives as an `Answer[T]`. See [Types](/v6/reference/types). |
 
 Grading, parameterizing at scale, and collecting tasks into tasksets are their own topic - see
-[Tasks & Tasksets](/v6/core/tasks).
+[Tasks & Tasksets](/v6/reference/tasks).
 
 ## The `Environment` object
 
 `hud.environment.Environment` is the lightweight control object the whole file hangs off. When
-served, it acts as the *server* an agent harness connects to over the [protocol](/v6/core/protocol):
+served, it acts as the *server* an agent harness connects to over the [protocol](/v6/advanced/protocol):
 it answers `hello` with its capabilities and runs its tasks on request.
 
 ```python
@@ -155,14 +155,14 @@ env = Environment(name="environment", version="0.0.1", capabilities=None)
 |-----------|------|---------|-------------|
 | `name` | `str` | `"environment"` | Environment identity (used as the env-ref name). |
 | `version` | `str` | `"0.0.1"` | Version string surfaced in the manifest. |
-| `capabilities` | `list[Capability] \| None` | `None` | Wire data for services that already exist; see [Capabilities](/v6/core/capabilities). |
+| `capabilities` | `list[Capability] \| None` | `None` | Wire data for services that already exist; see [Capabilities](/v6/reference/capabilities). |
 
 <Note>Passing v5-only keywords emits a `DeprecationWarning` and ignores them. See [Migrate to v6](/v6/more/migrate-v6).</Note>
 
 ## Serving
 
 You rarely serve by hand - `hud eval`, `task.run()`, and `Taskset.run()` bring the environment up for
-you, and the [runtime](/v6/core/runtime) you pass decides where. Serving itself belongs to
+you, and the [runtime](/v6/reference/runtime) you pass decides where. Serving itself belongs to
 `hud.environment.server`, the same entry point a container CMD runs
 (`python -m hud.environment.server <source>`):
 
@@ -205,13 +205,13 @@ end to end:
 ## See also
 
 <CardGroup cols={2}>
-<Card title="Capabilities" icon="plug" href="/v6/core/capabilities">
+<Card title="Capabilities" icon="plug" href="/v6/reference/capabilities">
   Every protocol factory, its params, and how to spin it up.
 </Card>
-<Card title="Tasks & Tasksets" icon="list-check" href="/v6/core/tasks">
+<Card title="Tasks & Tasksets" icon="list-check" href="/v6/reference/tasks">
   Add tasks that prompt and grade against this environment.
 </Card>
-<Card title="Runtime" icon="server" href="/v6/core/runtime">
+<Card title="Runtime" icon="server" href="/v6/reference/runtime">
   Point a harness at your environment and run it anywhere.
 </Card>
 <Card title="Composing richer environments" icon="layer-group" href="/v6/advanced/extending">
diff --git a/docs/v6/core/graders.mdx b/docs/v6/reference/graders.mdx
similarity index 97%
rename from docs/v6/core/graders.mdx
rename to docs/v6/reference/graders.mdx
index 651b3793..63a35393 100644
--- a/docs/v6/core/graders.mdx
+++ b/docs/v6/reference/graders.mdx
@@ -132,6 +132,6 @@ An `EvaluationResult` is the combined grade payload you can yield from a task:
 ## See also
 
 <CardGroup cols={2}>
-<Card title="Tasks & Tasksets" icon="list-check" href="/v6/core/tasks" />
-<Card title="Designing tasks" icon="signal" href="/v6/core/advice" />
+<Card title="Tasks & Tasksets" icon="list-check" href="/v6/reference/tasks" />
+<Card title="Designing tasks" icon="signal" href="/v6/reference/advice" />
 </CardGroup>
diff --git a/docs/v6/core/runtime.mdx b/docs/v6/reference/runtime.mdx
similarity index 96%
rename from docs/v6/core/runtime.mdx
rename to docs/v6/reference/runtime.mdx
index b5acd2da..479ea37a 100644
--- a/docs/v6/core/runtime.mdx
+++ b/docs/v6/reference/runtime.mdx
@@ -1,6 +1,6 @@
 ---
-title: "Run & deploy"
-description: "Run a HUD task by deploying the environment to the platform or by driving it programmatically from your machine, with the same task definition either way."
+title: "Runtimes"
+description: "Run a task by deploying to the platform or programmatically from your machine."
 icon: "rocket"
 ---
 
@@ -69,13 +69,13 @@ hud sync tasks my-taskset  # publish the taskset (uploads only what changed)
 `hud init` scaffolds the `Dockerfile.hud`. One build packs every task from the definition, so the same
 image runs unchanged on HUD, on a cloud sandbox, in CI, or on your laptop. After deploying,
 `HUDRuntime()` is the natural pair. Pass build config with `--env`, `--build-arg`, and `--secret`. See
-the [CLI reference](/v6/core/cli#hud-deploy) for the full flag set.
+the [CLI reference](/v6/reference/cli#hud-deploy) for the full flag set.
 
 ## RuntimeConfig
 
 `RuntimeConfig` carries the construction hints a container-based runtime needs: which image, how much
 hardware, and what timeouts. Set it on the runtime (`runtime_config=`) or per row on
-[`Task.runtime_config`](/v6/core/tasks#the-task-row); the runtime merges the two and applies what it
+[`Task.runtime_config`](/v6/reference/tasks#the-task-row); the runtime merges the two and applies what it
 supports.
 
 ```python
diff --git a/docs/v6/core/tasks.mdx b/docs/v6/reference/tasks.mdx
similarity index 90%
rename from docs/v6/core/tasks.mdx
rename to docs/v6/reference/tasks.mdx
index 703a88b0..2c5898bd 100644
--- a/docs/v6/core/tasks.mdx
+++ b/docs/v6/reference/tasks.mdx
@@ -4,10 +4,10 @@ description: "What a task is, how you define one, and how a single definition be
 icon: "list-check"
 ---
 
-An [environment](/v6/core/environment) is *where* the agent acts. A **task** is the *work* you measure
+An [environment](/v6/reference/environment) is *where* the agent acts. A **task** is the *work* you measure
 there. A task only ever does two things: it **prompts** the agent, and it **grades** what happened into
 a single number, the **reward**. That one number is the whole point - it's what an evaluation reports
-and what [training](/v6/core/training) learns from.
+and what [training](/v6/reference/training) learns from.
 
 Four words do all the work, and they're worth keeping apart:
 
@@ -46,7 +46,7 @@ task = count_letter(word="raspberry")   # a Task row, not yet run
 ```
 
 Declare `returns=T` on the template and the answer arrives as a parsed
-[`Answer[T]`](/v6/core/types) (`.content` parsed, `.raw` the original string); without it, `answer` is
+[`Answer[T]`](/v6/reference/types) (`.content` parsed, `.raw` the original string); without it, `answer` is
 the raw string the agent submitted.
 
 ## One definition, many tasks
@@ -76,7 +76,7 @@ substrate that placement brings up.
 | `columns` | `dict \| None` | Metadata surfaced as filter/leaderboard facets. |
 | `validation` | `list[dict] \| None` | Platform/sync metadata. |
 | `agent_config` | `dict \| None` | Per-task agent overrides (e.g. `{"max_steps": 50}`). |
-| `runtime_config` | `RuntimeConfig \| None` | Per-row launch hints (`image`, `resources`); the [runtime](/v6/core/runtime) applies what it supports. |
+| `runtime_config` | `RuntimeConfig \| None` | Per-row launch hints (`image`, `resources`); the [runtime](/v6/reference/runtime) applies what it supports. |
 
 When you don't have the template in hand (data pipelines, generated rows), build the model directly -
 the model *is* the row, so `task.model_dump()` and `Task.model_validate(data)` are the whole codec:
@@ -94,7 +94,7 @@ The second yield is the reward. The first decision is *what* you score:
 - **Grade the answer** - compute a float from what the agent said.
 - **Grade the world** - score the **state the agent left behind**: tests passing, a file written, a
   service responding. Because the agent acts on a real system through its
-  [capabilities](/v6/core/capabilities), this is often the most reliable signal. It's **outcome
+  [capabilities](/v6/reference/capabilities), this is often the most reliable signal. It's **outcome
   verification**: the rigor of a test suite, with no fixed protocol the agent has to follow.
 
 You reach for one of three approaches, in increasing power:
@@ -150,9 +150,9 @@ async def implement_feature(spec: str = "add a /health endpoint"):
 
 </AccordionGroup>
 
-The full catalog lives in the [Graders reference](/v6/core/graders). A grader that returns a constant
+The full catalog lives in the [Graders reference](/v6/reference/graders). A grader that returns a constant
 or just echoes the answer back teaches a model nothing and invites reward hacking; a good reward
-separates good work from bad - see [Designing tasks](/v6/core/advice).
+separates good work from bad - see [Designing tasks](/v6/reference/advice).
 
 ## Tasksets
 
@@ -201,7 +201,7 @@ print(job.reward)
 
 - **`runtime=`** chooses *where* each rollout runs (local subprocess, container, cloud sandbox, HUD).
   Swap it freely without touching the tasks; omit it and placement is inferred (a locally-authored
-  source serves itself, platform/file rows go HUD-hosted). See [Runtime](/v6/core/runtime).
+  source serves itself, platform/file rows go HUD-hosted). See [Runtime](/v6/reference/runtime).
 - **`group=`** repeats each task N times so you can see the reward spread (the grouping GRPO trains on).
 - **`max_concurrent=`** caps how many rollouts run in parallel.
 
@@ -217,7 +217,7 @@ traces, so even a single `task.run` returns a job of one.
 |--------|------|-------------|
 | `id` | `str` | HUD job id. |
 | `name` | `str` | Display name. |
-| `runs` | `list[Run]` | The graded [`Run`](/v6/core/types#run)s, in expansion order. |
+| `runs` | `list[Run]` | The graded [`Run`](/v6/reference/types#run)s, in expansion order. |
 | `group` | `int` | Rollouts per task. |
 | `reward` | `float` | Mean reward across all runs. |
 | `results` | `dict[str, list[Run]]` | Runs grouped by task slug - the alignment-safe alternative to `zip(tasks, runs)` (list-valued since `group > 1` gives several runs per task). |
@@ -266,16 +266,16 @@ print(plan.summary())
 ## See also
 
 <CardGroup cols={2}>
-<Card title="Environments" icon="cube" href="/v6/core/environment">
+<Card title="Environments" icon="cube" href="/v6/reference/environment">
   Where the agent acts, and the capabilities a task grades against.
 </Card>
-<Card title="Graders" icon="check-double" href="/v6/core/graders">
+<Card title="Graders" icon="check-double" href="/v6/reference/graders">
   Every grader, comparison helper, and the `combine` combiner.
 </Card>
-<Card title="Runtime" icon="server" href="/v6/core/runtime">
+<Card title="Runtime" icon="server" href="/v6/reference/runtime">
   Where each task runs, chosen at execution time.
 </Card>
-<Card title="Designing tasks" icon="lightbulb" href="/v6/core/advice">
+<Card title="Designing tasks" icon="lightbulb" href="/v6/reference/advice">
   Design tasks that actually teach: difficulty, spread, and resisting reward hacking.
 </Card>
 </CardGroup>
diff --git a/docs/v6/core/training.mdx b/docs/v6/reference/training.mdx
similarity index 95%
rename from docs/v6/core/training.mdx
rename to docs/v6/reference/training.mdx
index 47607641..6c2cdf49 100644
--- a/docs/v6/core/training.mdx
+++ b/docs/v6/reference/training.mdx
@@ -5,7 +5,7 @@ icon: "dumbbell"
 ---
 
 The key idea: **the rewards you collect are already training data.** Every rollout produced a
-trajectory (what the agent did) and a [reward](/v6/core/tasks) (how well it did). Training nudges the
+trajectory (what the agent did) and a [reward](/v6/reference/tasks) (how well it did). Training nudges the
 model's weights so the behavior that earned *high* reward becomes more likely next time. You feed that
 signal into **HUD's managed trainer** (the simple path, no ML infra) or into **your own** RL loop.
 
@@ -31,7 +31,7 @@ set that loop up.
 - **A task with spread in its rewards.** This is the one prerequisite people miss. If every rollout of
   a task gets the *same* reward, training learns nothing from it (see [Why grouping
   matters](#why-grouping-matters)). Designing tasks that produce spread is its own craft - see
-  [Designing tasks](/v6/core/advice).
+  [Designing tasks](/v6/reference/advice).
 - **A trainable model**, which you make by forking one (next).
 
 ## Get a trainable model
@@ -74,8 +74,8 @@ The one line that learns is `trainer.step(...)`. It computes how each rollout sh
 applies that shift, then checkpoints and **promotes** the new weights so the gateway serves them
 immediately. That's why the *next* `taskset.run` samples an improved model - the loop closes itself.
 
-The trainer's input is the rewards you already have: a [`Job`](/v6/core/tasks#jobs) holds the graded
-[`Run`](/v6/core/types#run)s from each batch, and you pass those runs (or a slice) straight to
+The trainer's input is the rewards you already have: a [`Job`](/v6/reference/tasks#jobs) holds the graded
+[`Run`](/v6/reference/types#run)s from each batch, and you pass those runs (or a slice) straight to
 `trainer.step`. Each `Run` carries its reward and either inline token samples or a `trace_id`, which is
 all the trainer needs (see [Inputs](#inputs)).
 
@@ -88,7 +88,7 @@ comparison to its siblings on the same task.
 The consequence: if every rollout in a group earns the **same** reward, every advantage is zero and
 **no learning happens** - no matter how high the average looks. That's why you run each task as a group
 (`group=8` above) and why your tasks must produce a **spread** of rewards. Trainability is a property of
-your tasks, not just your loop - the whole point of [Designing tasks](/v6/core/advice).
+your tasks, not just your loop - the whole point of [Designing tasks](/v6/reference/advice).
 
 ## Watch it improve
 
@@ -258,16 +258,16 @@ Under the hood `forward` returns a `ForwardResult` (`forward_id` + `data: list[D
 ## See also
 
 <CardGroup cols={2}>
-<Card title="Designing tasks" icon="lightbulb" href="/v6/core/advice">
+<Card title="Designing tasks" icon="lightbulb" href="/v6/reference/advice">
   Design tasks that produce reward spread - the prerequisite for training to work.
 </Card>
-<Card title="Tasks & Tasksets" icon="list-check" href="/v6/core/tasks">
+<Card title="Tasks & Tasksets" icon="list-check" href="/v6/reference/tasks">
   Where the rewards training learns from come from.
 </Card>
-<Card title="Run & deploy" icon="rocket" href="/v6/core/runtime">
+<Card title="Run & deploy" icon="rocket" href="/v6/reference/runtime">
   Scale the rollouts that feed the loop.
 </Card>
-<Card title="Types: Run & Trace" icon="code" href="/v6/core/types">
+<Card title="Types: Run & Trace" icon="code" href="/v6/reference/types">
   The Run a rollout produces and the trace it carries.
 </Card>
 </CardGroup>
diff --git a/docs/v6/core/types.mdx b/docs/v6/reference/types.mdx
similarity index 95%
rename from docs/v6/core/types.mdx
rename to docs/v6/reference/types.mdx
index 1ddaa607..66c7f9d0 100644
--- a/docs/v6/core/types.mdx
+++ b/docs/v6/reference/types.mdx
@@ -105,7 +105,7 @@ agent submits them as part of the answer.
 ### Grading shapes
 
 `SubScore` and `EvaluationResult` live with the graders - see
-[Graders](/v6/core/graders#subscore-and-evaluationresult).
+[Graders](/v6/reference/graders#subscore-and-evaluationresult).
 
 ## Typed task I/O
 
@@ -115,6 +115,6 @@ agent's answer into a typed `Answer[T]`. Any Pydantic model or standard type wor
 ## See also
 
 <CardGroup cols={2}>
-<Card title="Tasks & Tasksets" icon="list-check" href="/v6/core/tasks" />
-<Card title="Graders" icon="scale-balanced" href="/v6/core/graders" />
+<Card title="Tasks & Tasksets" icon="list-check" href="/v6/reference/tasks" />
+<Card title="Graders" icon="scale-balanced" href="/v6/reference/graders" />
 </CardGroup>
diff --git a/docs/v6/start/index.mdx b/docs/v6/start/index.mdx
index d9bcdac9..72bfb20a 100644
--- a/docs/v6/start/index.mdx
+++ b/docs/v6/start/index.mdx
@@ -39,7 +39,7 @@ flowchart LR
     end
 
     AG <-->|capabilities| EN
-    EN -->|humans measure| EV["<b>evaluation</b> and <b>benchmarking</b>"]
+    EN -->|humans measure| EV["<b>evaluation</b>#160;and#160;<b>benchmarking</b>"]
     EN -->|agent improves| TR["<b>training</b>"]
 
     classDef node fill:#efece8,stroke:#2b2722,stroke-width:1px,color:#2b2722;
@@ -56,8 +56,8 @@ flowchart LR
 ## Reading the docs
 
 - [**Quickstart**](/v6/start/quickstart) - install HUD and run your first graded task in minutes.
-- [**Overview**](/v6/build/overview) - the big picture of what HUD is and how the whole workflow fits together.
-- [**Core**](/v6/core/environment) - the heart of the docs: environments, tasks, agents, running, training, and more, each with a hands-on guide and its API.
+- [**Overview**](/v6/start/overview) - the big picture of what HUD is and how the whole workflow fits together.
+- [**Core**](/v6/reference/environment) - the heart of the docs: environments, tasks, agents, running, training, and more, each with a hands-on guide and its API.
 - [**Advanced**](/v6/advanced/extending) - off the beaten path: bring your own harness, composing environments, subagents, and chat.
 - [**Cookbooks**](/v6/cookbooks/coding-agent) - worked examples and creative ways to use HUD.
 - [**More**](/v6/more/faq) - FAQ, migrating to v6, and contributing.
@@ -66,10 +66,10 @@ flowchart LR
 <Card title="Quickstart" icon="bolt" href="/v6/start/quickstart">
   Install to your first graded trace in a few minutes.
 </Card>
-<Card title="Build" icon="compass" href="/v6/build/overview">
+<Card title="Build" icon="compass" href="/v6/start/overview">
   The full flow, start to finish: declare an environment, write tasks, run a model, deploy, and train.
 </Card>
-<Card title="Reference" icon="brackets-curly" href="/v6/core/environment">
+<Card title="Reference" icon="brackets-curly" href="/v6/reference/environment">
   Every SDK object, method, and type - like a great docstring.
 </Card>
 <Card title="Advanced" icon="puzzle-piece" href="/v6/advanced/extending">
diff --git a/docs/v6/start/quickstart.mdx b/docs/v6/start/quickstart.mdx
index aec00b1a..d67f93a0 100644
--- a/docs/v6/start/quickstart.mdx
+++ b/docs/v6/start/quickstart.mdx
@@ -31,7 +31,7 @@ Get a key from [hud.ai/project/api-keys](https://hud.ai/project/api-keys) - one
 hud set HUD_API_KEY=your-key-here
 ```
 
-## 3. Write a task
+## 3. Create a Test Environment
 
 Scaffold a complete, runnable example to start from:
 
@@ -62,20 +62,3 @@ hud eval tasks.py claude
 ```
 
 `hud eval` spawns the environment locally, runs the `claude` agent, and grades it. Every rollout generates a replayable trace on [hud.ai](https://hud.ai). 
-
-## Next
-
-<CardGroup cols={2}>
-<Card title="Package & deploy" icon="rocket" href="/v6/core/runtime">
-  Build a portable image and run it anywhere.
-</Card>
-<Card title="Add capabilities" icon="cube" href="/v6/core/environment">
-  Give the agent a shell, browser, GUI, or robot to act on.
-</Card>
-<Card title="Design tasks for signal" icon="signal" href="/v6/core/advice">
-  Make tasks that actually train, not just test.
-</Card>
-<Card title="Run on any model" icon="robot" href="/v6/core/agents">
-  Claude, OpenAI, Gemini, or your own endpoint.
-</Card>
-</CardGroup>

From 777e3d03a7dd5fecab7622008437936fe48de53f Mon Sep 17 00:00:00 2001
From: lukass16 <lukasskellijs@gmail.com>
Date: Wed, 24 Jun 2026 16:59:21 -0700
Subject: [PATCH 03/16] docs(v6): add split-layout and training guides

Add walkthrough pages for the env.py/tasks.py split layout and for
training models with HUD.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/v6/guides/split-layout-demo.mdx | 88 ++++++++++++++++++++++++++++
 docs/v6/guides/training-models.mdx   | 51 ++++++++++++++++
 2 files changed, 139 insertions(+)
 create mode 100644 docs/v6/guides/split-layout-demo.mdx
 create mode 100644 docs/v6/guides/training-models.mdx

diff --git a/docs/v6/guides/split-layout-demo.mdx b/docs/v6/guides/split-layout-demo.mdx
new file mode 100644
index 00000000..15325cd8
--- /dev/null
+++ b/docs/v6/guides/split-layout-demo.mdx
@@ -0,0 +1,88 @@
+---
+title: "Split Layout (Demo)"
+description: "A textbook-style two-column layout: explanation on the left, supporting visuals in the margin."
+icon: "table-columns"
+---
+
+This page demonstrates a minimal two-column guide layout. The left column holds the explanation and stays
+the center of attention; the right column is a quiet textbook margin for the supporting code, tables,
+diagrams, and notes that belong beside it. On narrow screens the columns stack, so each visual drops under
+the text it belongs to.
+
+<div className="guide-row">
+<div className="guide-main">
+
+### Declare the environment
+
+An environment is defined in a single `env.py`. Start with an `Environment` and at least one capability -
+the connection the agent drives. The fields below are the minimum a runnable environment needs.
+
+</div>
+<div className="guide-aside">
+
+<p className="aside-label">env.py</p>
+
+```python
+from hud.environment import Environment
+from hud.capabilities import Capability
+
+env = Environment(name="my-env", capabilities=[
+    Capability.ssh(name="shell", url="<url>"),
+])
+```
+
+| Field | Role |
+| --- | --- |
+| `name` | identifies the env |
+| `capabilities` | what the agent drives |
+
+</div>
+</div>
+
+<div className="guide-row">
+<div className="guide-main">
+
+### Lifecycle
+
+Optional hooks run setup and teardown around each rollout. Use them only when a task needs fixtures,
+services, or seed state - stateless tasks skip them entirely.
+
+</div>
+<div className="guide-aside">
+
+<p className="aside-label">lifecycle</p>
+
+```mermaid
+flowchart TB
+    I["initialize"] --> S["serve task"] --> D["shutdown"]
+    classDef n fill:#efece8,stroke:#2b2722,color:#2b2722;
+    class I,S,D n;
+```
+
+</div>
+</div>
+
+<div className="guide-row">
+<div className="guide-main">
+
+### Grade a task
+
+A task prompts the agent and returns a reward. The final `yield` is the score - that number, with the
+trace, is what you read in an eval and feed into training.
+
+</div>
+<div className="guide-aside">
+
+<p className="aside-label">graded task</p>
+
+```python
+@env.template()
+async def task(target: str = "..."):
+    answer = yield f"<prompt {target}>"
+    yield 1.0 if answer == target else 0.0
+```
+
+<Note>The reward is a single number between 0 and 1.</Note>
+
+</div>
+</div>
diff --git a/docs/v6/guides/training-models.mdx b/docs/v6/guides/training-models.mdx
new file mode 100644
index 00000000..d107fc0a
--- /dev/null
+++ b/docs/v6/guides/training-models.mdx
@@ -0,0 +1,51 @@
+---
+title: "Training Agents"
+description: "Group rollouts per task, read the reward spread, and feed it into your RL loop."
+icon: "dumbbell"
+---
+
+Evaluation and training share the same machinery: a task, an agent, and a reward. To train, you run many
+rollouts of the same task, look at how the rewards spread, and use that signal to update the model.
+
+## 1. Group rollouts per task
+
+Run a group of rollouts for each task instead of a single attempt. The spread of rewards within a group
+is the learning signal - a task every rollout passes (or fails) teaches nothing.
+
+```python
+from hud.eval import LocalRuntime
+from tasks import TASKS
+
+job = await TASKS.run(agent, runtime=LocalRuntime("env.py"), group=8)   # 8 rollouts per task
+```
+
+## 2. Read the reward spread
+
+Each group yields a distribution of rewards. A healthy training task has variance - some rollouts succeed,
+some don't - so the policy has a gradient to climb.
+
+```python
+for task_group in job.groups:
+    print(task_group.rewards)        # e.g. [1.0, 0.0, 1.0, 0.0, 1.0, 1.0, 0.0, 1.0]
+```
+
+## 3. Feed it into your RL loop
+
+Hand the grouped rewards straight to your own GRPO/PPO loop, or a stack like
+[Tinker](https://thinkingmachines.ai/tinker/), [slime](https://github.com/THUDM/slime), or
+[Fireworks](https://fireworks.ai/). The environment and reward stay fixed; everything else is yours to
+swap.
+
+## Where to go next
+
+<CardGroup cols={2}>
+<Card title="Training" icon="dumbbell" href="/v6/reference/training">
+  The training reference: groups, rewards, and RL integration.
+</Card>
+<Card title="Evaluating Agents" icon="play" href="/v6/guides/running-an-eval">
+  Form a taskset and run an agent against it.
+</Card>
+<Card title="Designing tasks" icon="signal" href="/v6/reference/advice">
+  Build tasks with the variance that makes training work.
+</Card>
+</CardGroup>

From 100ca21a9f277e192beb88e04ab557a19682aaf1 Mon Sep 17 00:00:00 2001
From: lukass16 <lukasskellijs@gmail.com>
Date: Wed, 24 Jun 2026 16:59:21 -0700
Subject: [PATCH 04/16] docs(v6): add creating-an-environment guide

Add a step-by-step guide for scaffolding an environment, defining tasks,
and running a first eval with the blank strawberry template.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/v6/guides/creating-an-environment.mdx | 208 +++++++++++++++++++++
 1 file changed, 208 insertions(+)
 create mode 100644 docs/v6/guides/creating-an-environment.mdx

diff --git a/docs/v6/guides/creating-an-environment.mdx b/docs/v6/guides/creating-an-environment.mdx
new file mode 100644
index 00000000..6a01d587
--- /dev/null
+++ b/docs/v6/guides/creating-an-environment.mdx
@@ -0,0 +1,208 @@
+---
+title: "Creating Environments"
+description: "Scaffold an environment, write its env.py, test it locally, and deploy it to the platform."
+icon: "hammer"
+mode: "wide"
+---
+
+
+This guide outlines how to create an environment in the HUD format - defining the `env.py` file, registering tasks
+and capabiltiies, doing quick local tests, and deploying the environment to our platform.
+
+## Start
+
+Run `hud init` in your terminal. This lets you select a template to start with, the default is a blank template.
+
+```bash
+hud init my-env
+cd my-env
+```
+
+Inside the blank template `my-env` you now have four files, each with one job:
+
+<div className="filetree">
+  <div className="ft-root">my-env/</div>
+  <div className="ft-row"><span><span className="ft-branch">├── </span><span className="ft-name">env.py</span></span><span className="ft-note">the environment: object, capabilities, and task definitions</span></div>
+  <div className="ft-row"><span><span className="ft-branch">├── </span><span className="ft-name">tasks.py</span></span><span className="ft-note">the concrete tasks to run, filled in with real arguments</span></div>
+  <div className="ft-row"><span><span className="ft-branch">├── </span><span className="ft-name">Dockerfile.hud</span></span><span className="ft-note">how the environment is packaged into an image on deploy</span></div>
+  <div className="ft-row"><span><span className="ft-branch">└── </span><span className="ft-name">pyproject.toml</span></span><span className="ft-note">the Python dependencies</span></div>
+</div>
+
+## The `env.py` file
+
+`env.py` is the only file that defines behavior. Here is a complete one: an environment that gives the
+agent a calculator tool, asks it to add two numbers, and scores the answer. We'll take it part by part,
+top to bottom.
+
+<Accordion title="Full env.py">
+
+```python env.py
+import asyncio
+
+from fastmcp import FastMCP
+
+from hud.capabilities import Capability
+from hud.environment import Environment
+
+server = FastMCP(name="calc-tools")
+
+@server.tool
+def add(a: int, b: int) -> int:
+    """Add two integers."""
+    return a + b
+
+env = Environment(name="calc")
+_server_task: asyncio.Task | None = None
+
+@env.initialize
+async def _up():
+    global _server_task
+    if _server_task is None:
+        _server_task = asyncio.create_task(
+            server.run_async(transport="http", host="127.0.0.1", port=8040)
+        )
+        await asyncio.sleep(1.0)   # wait until the server is listening
+    env.add_capability(Capability.mcp(name="tools", url="http://127.0.0.1:8040/mcp"))
+
+@env.shutdown
+async def _down():
+    global _server_task
+    if _server_task is not None:
+        _server_task.cancel()
+        _server_task = None
+
+@env.template(id="sum")
+async def sum_task(a: int, b: int):
+    answer = yield f"Use your tools to compute {a} + {b}. Reply with just the number."
+    yield 1.0 if str(a + b) in (answer or "") else 0.0
+```
+
+</Accordion>
+
+```python
+env = Environment(name="calc")
+```
+
+This creates the **`Environment` object**. It holds nothing on its own; it's the handle you register
+everything else against. Every capability and task that follows attaches to `env`. The `name` is how a
+task row later finds its way back to this definition. When HUD runs the environment, it imports the
+file, finds this object, and serves whatever is registered on it, which is why the same `env.py` runs
+on your laptop, in a container, or on the platform unchanged.
+
+## Capabilities
+
+A **capability** is a connection the agent drives. This environment serves its own: a
+[FastMCP](https://gofastmcp.com) server exposing one tool, `add`. Three things happen, in order, inside
+the lifecycle hooks:
+
+```python
+@env.initialize          # runs once before the env accepts any connection
+async def _up():
+    # 1. start the tool server in the background
+    _server_task = asyncio.create_task(server.run_async(transport="http", host="127.0.0.1", port=8040))
+    await asyncio.sleep(1.0)                                  # 2. wait until it's listening
+    env.add_capability(Capability.mcp(name="tools",          # 3. publish its address
+                                      url="http://127.0.0.1:8040/mcp"))
+
+@env.shutdown            # runs on shutdown
+async def _down():
+    _server_task.cancel()                                    # tear it down with the env
+```
+
+`@env.initialize` runs to completion before any agent connects, so by the time one does, the tool is
+live. Step 2 matters: a background task returns before the server has bound its port, and publishing
+the capability too early lets an agent connect to nothing. `@env.shutdown` releases it.
+
+You attach a capability three ways:
+
+- in the `Environment(...)` constructor, for a service that already exists,
+- with `env.add_capability(...)` from a hook, for a service the environment runs itself (above),
+- with `env.workspace(root)`, the one-line shortcut for the common case: a sandboxed shell over `ssh`.
+
+Other protocols - a browser over `cdp`, a full desktop over `rfb`, a robot loop - attach the same way.
+The [capabilities](/v6/reference/capabilities) page has the spin-up for each.
+
+## Tasks
+
+```python
+@env.template(id="sum")
+async def sum_task(a: int, b: int):
+    answer = yield f"Use your tools to compute {a} + {b}. Reply with just the number."
+    yield 1.0 if str(a + b) in (answer or "") else 0.0
+```
+
+A task is an async generator with two `yield`s. The first yields the prompt; the agent then works,
+calling the `add` tool, and its answer comes back into `answer`; the second yields the reward. Whatever
+the agent does happens between the two yields.
+
+`@env.template()` registers the function as a **template**. Its parameters (`a`, `b`) fill in per run,
+so one definition covers a whole space of tasks. Calling it - `sum_task(a=2, b=3)` - binds one runnable
+[task](/v6/reference/tasks).
+
+## Grading
+
+The second yield is the reward, a number from `0.0` to `1.0`. Here it's plain Python: compare the
+answer to `a + b`. You have three options as tasks grow:
+
+| Approach | What it does |
+| --- | --- |
+| Plain Python | Compute the float inline, like above. Comparison helpers (`exact_match`, `numeric_match`, ...) live in `hud.graders`. |
+| Async graders | `BashGrader` scores a shell command by exit code; `LLMJudgeGrader` scores against rubric criteria. This is how you grade the state the agent left behind - a test passing, a file written. |
+| Composed graders | `combine` runs several at once and weights them into one reward, each subscore visible in the trace. |
+
+Grading the state the agent left behind is usually the most reliable signal. A grader that returns a
+constant invites reward hacking; see [designing tasks](/v6/reference/advice) for what separates good
+work from bad.
+
+## Listing tasks in `tasks.py`
+
+`env.py` defines the shape of a task. `tasks.py` lists the concrete ones to run by calling the template
+with real arguments:
+
+```python tasks.py
+from env import sum_task
+
+tasks = [
+    sum_task(a=2, b=3),
+    sum_task(a=10, b=15),
+]
+```
+
+Each call binds one runnable task. Build them in a loop to turn one definition into a whole dataset.
+
+## Testing the environment locally
+
+Run an agent against the tasks. `hud eval` spawns the environment locally, runs the agent, grades each
+task, and prints the reward:
+
+```bash
+hud eval tasks.py claude
+```
+
+That's the whole local loop - no API key, no Docker, no separate server. Use it while iterating.
+
+## Deploying to the platform
+
+When it works locally, ship it. Deploying talks to the platform, so set your API key first:
+
+```bash
+hud set HUD_API_KEY=your-key   # get one at hud.ai
+```
+
+`hud deploy` builds the image from `Dockerfile.hud` and publishes the environment under its
+`Environment(name=...)`:
+
+```bash
+hud deploy
+```
+
+To run a taskset from the platform, publish it too. `hud sync` uploads a taskset and only what changed:
+
+```bash
+hud sync tasks my-tasks   # publish tasks.py as a named taskset
+hud sync env              # sync environment metadata
+```
+
+Your environment now lives on the platform, ready to run at scale and compare across models. Running
+those evaluations - locally, on a cloud sandbox, or on the platform - is covered in
+[evaluating agents](/v6/guides/running-an-eval).

From 1ddf0d929db75f54e5cef7e01ea3eb714e8ecbd7 Mon Sep 17 00:00:00 2001
From: lukass16 <lukasskellijs@gmail.com>
Date: Wed, 24 Jun 2026 16:59:21 -0700
Subject: [PATCH 05/16] docs(v6): add running-an-eval guide

Add a guide for configuring agents, running evals locally, and reading
results with hud eval.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/v6/guides/running-an-eval.mdx | 160 +++++++++++++++++++++++++++++
 1 file changed, 160 insertions(+)
 create mode 100644 docs/v6/guides/running-an-eval.mdx

diff --git a/docs/v6/guides/running-an-eval.mdx b/docs/v6/guides/running-an-eval.mdx
new file mode 100644
index 00000000..ac61dbeb
--- /dev/null
+++ b/docs/v6/guides/running-an-eval.mdx
@@ -0,0 +1,160 @@
+---
+title: "Running an Eval"
+description: "Run an agent against your tasks - from the platform or from a local environment - and read the reward."
+icon: "play"
+---
+
+`hud eval` is the central command for all evaluations. It works whether your environment lives on the HUD platform or in a local `env.py`, and every rollout it produces lands as a traced, replayable entry in your [platform dashboard](https://hud.ai). The mechanics underneath - the control channel, `tasks.start`, `tasks.grade` - are documented in [Protocol](/v6/advanced/protocol).
+
+The two workflows differ only in where your environment lives:
+
+| | When to use | Entry points |
+| --- | --- | --- |
+| [**Deployed environment**](#deployed-environment) | Env is built and hosted on HUD | Terminal or platform UI |
+| [**Local environment**](#local-environment) | `env.py` is on your disk | Terminal or run script |
+
+---
+
+## Deployed environment
+
+A **deployed environment** is one that has been built and published to HUD with [`hud deploy`](/v6/guides/creating-an-environment#deploy-it), or an existing environment from the [platform catalog](https://hud.ai/environments/new). The environment runs entirely on HUD's hosted infra - there is no local process to manage.
+
+Two entry points are available, and both trace to the same dashboard.
+
+**From the terminal.** Pass the taskset name or id to `hud eval`. The tasks are fetched from the platform and each rollout runs remotely on HUD's infra:
+
+```bash
+hud eval "My Taskset" claude
+hud eval "My Taskset" claude --all --group 3
+```
+
+**From the platform.** Open [hud.ai](https://hud.ai), select your environment, choose a taskset and a model, and launch from the dashboard. No CLI required.
+
+### Choosing an agent
+
+The agent shorthand (`claude`, `openai`, `gemini`) selects a built-in harness and routes LLM calls through the [HUD gateway](/v6/reference/agents) - a single `HUD_API_KEY` covers every provider, so switching models is one flag:
+
+```bash
+hud eval "My Taskset" claude --model claude-haiku-4-5   # cheaper model for fast iteration
+hud eval "My Taskset" openai --model gpt-5
+hud eval "My Taskset" gemini
+```
+
+To see every model the gateway supports, run `hud models list`. For a custom harness - a fine-tuned model, a framework you already use - see [Bring your own harness](/v6/advanced/extending#bring-your-own-harness).
+
+### Traces and results
+
+Each rollout is a **trace**: a replayable timeline of every action the agent took and the reward it received. All traces are visible on the [HUD dashboard](https://hud.ai), grouped into a **job**. You can also inspect them from the CLI:
+
+```bash
+hud jobs               # recent jobs - id, name, taskset, status
+hud jobs <job-id>      # traces for that job
+hud trace <trace-id>   # one rollout in full
+```
+
+---
+
+## Local environment
+
+A local environment is an `env.py` on your disk. This is the typical workflow during environment development. `hud eval` is the preferred entry point; a run script gives you programmatic control when you need it.
+
+Both paths accept a [runtime](/v6/reference/runtime) - the one argument that decides where each rollout runs. The environment definition never changes; only the runtime changes.
+
+<Note>
+With a `HUD_API_KEY` set, local evals also trace to the [platform dashboard](https://hud.ai). Without one, rollouts run and grade locally with no platform calls.
+</Note>
+
+### Using `hud eval`
+
+`hud eval` is the preferred local iteration loop. It spawns the env subprocess automatically - you do not need `hud serve` running, a Docker daemon, or a HUD API key for a purely local run.
+
+<div className="guide-row">
+<div className="guide-main">
+
+Point `hud eval` at your task source and pass an agent name. By default, each rollout runs in a local child process from your `env.py`:
+
+```bash
+hud eval tasks.py claude                             # first task, one rollout
+hud eval tasks.py claude --all                       # every task
+hud eval tasks.py claude --group 3                   # 3 rollouts per task
+hud eval tasks.py claude --runtime hud               # run on HUD's hosted infra
+hud eval tasks.py claude --runtime tcp://host:8765   # attach to a running substrate
+```
+
+The `--runtime` flag sets where each rollout executes. Omit it for the fastest local loop. For the full flag set, see [`hud eval`](/v6/reference/cli#hud-eval).
+
+</div>
+<div className="guide-aside">
+
+<p className="aside-label">--runtime options</p>
+
+| `--runtime` | Where the env runs | Requires |
+| --- | --- | --- |
+| *(omitted)* | Child process on your machine | Nothing |
+| `hud` | HUD's hosted infra | `hud deploy` first |
+| `tcp://host:port` | A substrate you already started | A running server |
+
+</div>
+</div>
+
+### Using a run script
+
+When you want programmatic control - looping over agents, integrating into a training pipeline, or routing tasks to different infra - call `taskset.run` directly and pass a [runtime](/v6/reference/runtime) object:
+
+```python run.py
+import asyncio
+from hud import Taskset, LocalRuntime
+from hud.agents import create_agent
+
+agent = create_agent("claude-sonnet-4-5")
+ts = Taskset.from_file("tasks.py")
+
+async def main():
+    job = await ts.run(agent, runtime=LocalRuntime("env.py"))
+    print(job.reward)
+
+asyncio.run(main())
+```
+
+Swap the runtime to change where the env runs without touching `env.py` or the tasks:
+
+| Runtime | Where the env runs |
+| --- | --- |
+| `LocalRuntime("env.py")` | Child process on your machine |
+| `DockerRuntime("my-env")` | Fresh local container per rollout |
+| `ModalRuntime("my-env")` | Fresh [Modal](https://modal.com) sandbox per rollout |
+| `DaytonaRuntime("my-env")` | Fresh [Daytona](https://daytona.io) sandbox per rollout |
+| `HUDRuntime()` | HUD's hosted infra (after `hud deploy`) |
+| `Runtime("tcp://host:port")` | A substrate you started yourself |
+
+For constructor details and how to bring your own runtime, see [Runtime](/v6/reference/runtime).
+
+### `hud serve`
+
+`hud eval` starts and stops the env subprocess automatically. `hud serve` exposes the same control channel as a standalone long-lived process - useful when you want to talk to a running env directly from a script, test a packaged image manually, or drive `hud task start` and `hud task grade` by hand:
+
+```bash
+hud serve            # auto-detect env.py, bind :8765
+hud serve env.py -p 9000
+```
+
+From a script, attach with `Runtime("tcp://localhost:8765")`; from `hud eval`, pass `--runtime tcp://localhost:8765`. The [Protocol reference](/v6/advanced/protocol) documents every message the control channel speaks.
+
+---
+
+## Where to go next
+
+<CardGroup cols={2}>
+<Card title="Deploying an environment" icon="rocket" href="/v6/guides/creating-an-environment#deploy-it">
+  Build your env into a platform image with `hud deploy`.
+</Card>
+<Card title="Runtimes" icon="server" href="/v6/reference/runtime">
+  Every built-in runtime and how to bring your own.
+</Card>
+<Card title="Agents" icon="robot" href="/v6/reference/agents">
+  Swap the model with a string, or bring your own harness.
+</Card>
+<Card title="Protocol" icon="route" href="/v6/advanced/protocol">
+  How an agent and an environment communicate.
+</Card>
+</CardGroup>

From 9908bb6d94e628cf8d0d203e514c528c147a13b0 Mon Sep 17 00:00:00 2001
From: lukass16 <lukasskellijs@gmail.com>
Date: Wed, 24 Jun 2026 16:59:22 -0700
Subject: [PATCH 06/16] docs(v6): rewrite start overview

Replace the old build overview with a start-page overview that orients
new users around the v6 docs structure and core workflows.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/v6/start/overview.mdx | 246 +++++++++++++++++++++++++++++++++++++
 1 file changed, 246 insertions(+)
 create mode 100644 docs/v6/start/overview.mdx

diff --git a/docs/v6/start/overview.mdx b/docs/v6/start/overview.mdx
new file mode 100644
index 00000000..0f0ac2f9
--- /dev/null
+++ b/docs/v6/start/overview.mdx
@@ -0,0 +1,246 @@
+---
+title: "Overview"
+description: "A concise, high-level explanation of core HUD concepts and the central workflow in one page."
+icon: "compass"
+mode: "wide"
+---
+
+This page reviews HUD-specific core concepts and overviews a full workflow. We'll go through the
+workflow and introduce all the core concepts as they arise. We'll include some code snippets, but for
+specific guides on the main uses see Guides. The workflow can be split into 5 steps:
+
+```mermaid
+%%{init: {'flowchart': {'padding': 22}}}%%
+flowchart LR
+    A(["1#160;·#160;Declare#160;your#160;environment"]) --> B(["2#160;·#160;Choose#160;your#160;taskset"]) --> C(["3#160;·#160;Choose#160;your#160;runtime"]) --> D(["4#160;·#160;Run#160;your#160;agent"]) --> E(["5#160;·#160;Learn"])
+    classDef s1 fill:#efece8,stroke:#2b2722,stroke-width:1px,color:#2b2722;
+    classDef s2 fill:#efece8,stroke:#2b2722,stroke-width:1px,color:#2b2722;
+    classDef s3 fill:#efece8,stroke:#2b2722,stroke-width:1px,color:#2b2722;
+    classDef s4 fill:#efece8,stroke:#2b2722,stroke-width:1px,color:#2b2722;
+    classDef s5 fill:#efece8,stroke:#2b2722,stroke-width:1px,color:#2b2722;
+    class A s1;
+    class B s2;
+    class C s3;
+    class D s4;
+    class E s5;
+    click A href "#1-·-declare-your-environment" _self
+    click B href "#2-·-choose-your-taskset" _self
+    click C href "#3-·-choose-your-runtime" _self
+    click D href "#4-·-run-your-agent" _self
+    click E href "#5-·-learn" _self
+```
+
+## 1 · Declare your environment
+
+In HUD any workflow starts either by creating your own environment or choosing an existing one.
+
+An environment is some closed container for your agent to act in. Fundamentally it's defined by:
+
+<div className="tight-list">
+
+- the **contents** of the container like files or environment state
+- the **tasks** to be performed inside it
+- the **grading mechanism** associated with each task
+- the **capabilities** the agent can use to perform these tasks
+
+</div>
+
+HUD maps each of these abstractions to a core concept you can compose and reuse:
+
+| Concept | What it is in HUD |
+| --- | --- |
+| [**Environment**](/v6/reference/environment) | The closed container the agent acts in - its contents, state, and lifecycle. |
+| [**Tasks & Tasksets**](/v6/reference/tasks) | A single task bound to an environment, each with its own prompt; bundle many task instances into a taskset. |
+| [**Graders**](/v6/reference/graders) | The mechanism associated with a specific task that scores an attempt and turns it into a reward. |
+| [**Capabilities**](/v6/reference/capabilities) | The interfaces the agent drives to act - shell, browser, screen, robot. |
+
+All of these abstractions appear in the `env.py` file - the central declarative file that describes
+everything there is to a HUD environment. For a dedicated overview, see our guide on [creating environments](/v6/guides/creating-an-environment).
+
+<Accordion title="Part 1: Declare your environment">
+
+The first and **key** part of any HUD workflow is **declaring your [environment](/v6/reference/environment)**
+in a declaration file `env.py` - here is a standard scaffold:
+
+```python env.py
+from hud.environment import Environment
+from hud.capabilities import Capability
+from hud.graders import LLMJudgeGrader
+
+# VITAL: an env with at least one capability - this is what the agent connects to and drives
+env = Environment(name="...", capabilities=[
+    Capability.ssh(name="shell", url="<url>", host_pubkey="<key>"),  # a real shell over ssh
+])
+
+# OPTIONAL: lifecycle hooks - only if the task needs setup/teardown (fixtures, services, seed state)
+@env.initialize               # runs once before serving
+async def _up():
+    ...                       # write fixtures, stand up services, etc.
+
+@env.shutdown                 # runs on env.stop()
+async def _down():
+    ...
+
+# VITAL: at least one task definition - prompts the agent and returns a reward
+@env.template()               # one definition = a whole space of tasks
+async def some_task_1(...):
+    answer = yield "<prompt>"      # the prompt handed to the agent; the agent's answer comes back
+    # ── everything the agent does happens here: it drives the capability until it's done ──
+    result = await LLMJudgeGrader.grade(answer=answer, criteria=[...])   # score the result → reward
+    yield result.value           # VITAL: the final yield is the reward
+```
+
+This scaffold is general on purpose - it describes _any_ environment. A one-line shell task, a full GUI
+desktop, a robot simulator - they're all just environments with some bespoke **content**, **tasks**, and
+associated **capabilities**. The complexity hidden under this file is hidden in the
+[HUD protocol](/v6/advanced/protocol) Its thin envelope lets any model or harness plug into any environment.
+
+
+</Accordion>
+
+
+
+## 2 · Choose your taskset
+
+Once an environment is defined or chosen, the next part is to simply select the set of tasks to use
+on that environment for evaluation. The core abstraction for this in HUD is the [Taskset](/v6/reference/tasks). 
+
+<Accordion title="Part 2: Choose your taskset">
+
+To form a [taskset](/v6/reference/tasks) (one or more tasks with parameters) do this directly **in code** 
+by importing from `env.py` or load them **from a file**. 
+HUD provides various ways to load, select, and run tasks. For a dedicated overview see our guide on
+[evaluating agents](/v6/guides/running-an-eval).
+
+```python tasks.py
+from hud.eval import Taskset
+from env import some_task_1, some_task_2
+
+# VITAL: a named taskset of concrete tasks to evaluate (parametrize one definition into many)
+TASKS = Taskset("my-taskset", [some_task_1(<args1>), some_task_1(<args2>), some_task_2(<args3>)])
+```
+
+</Accordion>
+
+## 3 · Choose your runtime
+
+Any kind of environment needs to actually run somewhere. An environment shouldn't care where 
+it runs - it should just work. HUD lets you run agent evaluations by deploying your environment to our platform on
+[hud.ai](https://hud.ai). For more customizability and local development, however, we use the [Runtime](/v6/reference/runtime).
+
+| Concept | What it is in HUD |
+| --- | --- |
+| [**Runtime**](/v6/reference/runtime) | Where an environment runs - locally, on a third-party provider, or the HUD platform - selected without changing the environment definition. |
+
+HUD provides you freedom to flexibly switch between running your environment 
+locally for fast environment development, on third-party runtime providers like
+[Daytona](https://www.daytona.io/), [Modal](https://modal.com/), or [E2B](https://e2b.dev/) for scale,
+or [deploy to the HUD platform](/v6/reference/runtime). The environment definition never changes - just the
+[Runtime](/v6/reference/runtime) you pass.
+
+<Accordion title="Part 3: Choose your runtime">
+
+There are **three ways** to run your declared environments. The main distinction is simply **where your
+environment file lives** - on your local drive, or packaged and deployed to the HUD platform.
+
+**1. From the CLI with `hud eval` (preferred).** Point it at your on-disk `env.py` (or `tasks.py`) and choose
+where each rollout runs with `--runtime`:
+
+```bash
+hud eval env.py claude                  # run locally against your on-disk env
+hud eval env.py claude --runtime hud    # same env, executed on HUD's hosted infra
+```
+
+**2. From a script.** The same eval embedded in Python when you want programmatic control - pick a
+[runtime](/v6/reference/runtime) and run a taskset against it:
+
+```python
+from hud.eval import LocalRuntime, DockerRuntime, ModalRuntime, HUDRuntime
+
+LocalRuntime("env.py")     # local child process - fastest iteration
+DockerRuntime("my-env")    # a fresh container per rollout
+ModalRuntime("my-env")     # a Modal cloud sandbox per rollout
+HUDRuntime()               # HUD's hosted infra (after `hud deploy`)
+```
+
+**3. Deploy to the platform.** Build a portable image once and push it to HUD - now your environment lives
+remotely, so you can run tasksets from the [platform](https://hud.ai), compare models, and browse every
+trace with no local infra:
+
+```bash
+hud deploy                 # build + register your env image on HUD
+hud sync tasks my-taskset  # publish a taskset to run from the platform
+```
+
+</Accordion>
+
+## 4 · Run your agent
+
+The next step is to choose
+the **agent** you want to evaluate.
+For standard models like Claude, GPT, or Gemini our **prebuilt harnesses** and our optional inference gateway
+let you switch between models just by choosing their name. 
+
+Running the agent evaluation produces a **run** (one rollout). Everry run is recorded into a **trace** - a full,
+replayable timeline of everything the agent did and how it was graded. Running a whole taskset bundles all 
+the runs into a single **job**. HUD enables executing runs in parallel with full isolation out of the box, and every
+run is traced on the [platform](https://hud.ai), so you can see exactly what the agent did in realtime.
+
+| Concept | What it is in HUD |
+| --- | --- |
+| [**Agent**](/v6/reference/agents) | A model paired with a harness that drives it - plugged into an environment's capabilities to attempt tasks and be graded. |
+| [**Run**](/v6/reference/types#run) | A single rollout - one agent attempting one task - that produces a reward. |
+| [**Trace**](/v6/reference/types#trace) | The full, replayable timeline of a run: every action, observation, and grade. |
+| [**Job**](/v6/reference/tasks#jobs) | A collection of runs grouped together - e.g. a whole taskset evaluated by an agent. |
+
+<Accordion title="Part 4: Run your agent">
+
+You can run this programmatically:
+
+```python
+from hud.agents import create_agent
+from hud.eval import LocalRuntime
+from tasks import TASKS
+
+agent = create_agent("claude-sonnet-4-5")               # routed through the HUD gateway
+
+job = await TASKS.run(agent, runtime=LocalRuntime("env.py"))   # start the run
+print(job.reward)
+```
+{/*
+<Note>You need a `HUD_API_KEY` ([hud.ai](https://hud.ai/project/api-keys)) for the gateway and tracing, or a provider key (`ANTHROPIC_API_KEY`, …) to call a model directly. See [Run on any model](/v6/reference/agents).</Note> */}
+
+
+
+or run it from the [CLI](/v6/reference/cli):
+```bash
+hud eval env.py claude --group 3
+```
+
+
+</Accordion>
+
+## 5 · Learn
+
+With runs in hand, you can **learn** from their signals - *evaluating* a model, *benchmarking* it against
+others, or *training* it to improve. For training, the **training client** turns the rewards from your runs
+into model updates you can plug straight into your RL stack.
+
+| Concept | What it is in HUD |
+| --- | --- |
+| [**Training Client**](/v6/reference/training#trainingclient) | Drives managed training for a model - turning the rewards collected from runs into gradient updates you feed into your RL loop. |
+
+<Accordion title="Part 5: Learn">
+
+HUD can directly provide rewards for your runs based on the **grader**. 
+These can then be used for your [training](/v6/reference/training): run a group per task and feed the
+spread straight into your own GRPO/PPO loop - or a stack like
+[Tinker](https://thinkingmachines.ai/tinker/), [slime](https://github.com/THUDM/slime), or
+[Fireworks](https://fireworks.ai/).
+
+</Accordion>
+
+## Where to next
+
+Go hands-on with the [Guides](/v6/guides/creating-an-environment), or dig into the full
+[Reference](/v6/reference/environment).

From 89a5aff9d84a21811fcd6c51e85fe505d68ac1b0 Mon Sep 17 00:00:00 2001
From: lukass16 <lukasskellijs@gmail.com>
Date: Wed, 24 Jun 2026 16:59:22 -0700
Subject: [PATCH 07/16] docs(v6): improve docs styling and layout

Extend custom.css with layout and typography tweaks for the restructured
v6 documentation site.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/custom.css | 155 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 155 insertions(+)

diff --git a/docs/custom.css b/docs/custom.css
index 5816ccbf..c0c76b30 100644
--- a/docs/custom.css
+++ b/docs/custom.css
@@ -418,3 +418,158 @@ body::after {
   white-space: nowrap;
   border: 0;
 }
+
+/* ── Collapsible sidebar sections ("toggle masquerading as a heading") ──────
+   Mintlify makes a section collapsible by nesting a group inside it, but it
+   renders that nested group as a <button> styled like a plain page link.
+   Restyle the toggle so it reads as a section heading (matching the always-open
+   "Start here" / "Guides" / "Reference" / "More" headings), keeping its chevron
+   as the expand/collapse affordance. The redundant outer wrapper heading is
+   hidden. This keys off the nested-group structure (`li[data-group-tag]`), so it
+   applies to exactly whichever sections are authored as nested groups in
+   docs.json — currently Advanced and Cookbooks. */
+li[data-group-tag] > button[aria-expanded] {
+  font-size: 0.75rem !important;   /* text-xs */
+  line-height: 1rem !important;
+  font-weight: 600 !important;     /* font-semibold */
+  color: #111827 !important;       /* gray-900 */
+}
+.dark li[data-group-tag] > button[aria-expanded] {
+  color: #e5e7eb !important;       /* gray-200 */
+}
+/* the section's pages sit one nesting level deeper than other sections — pull
+   them back to the standard page-link indent so they line up identically. */
+li[data-group-tag] ul a {
+  padding-left: 1rem !important;
+}
+/* hide the redundant outer section heading that wraps a collapsible toggle */
+div:has(> ul.sidebar-group > li[data-group-tag]) > .sidebar-group-header {
+  display: none !important;
+}
+
+/* ── Mermaid diagrams: stop labels overflowing their boxes ──────────────────
+   Mermaid measures each node box using its *default* font (trebuchet ms), but
+   the page then inherits the wider HUD brand font (Inter), so the rendered
+   text no longer fits the box it was sized for and the last letters clip. The
+   simple, root-cause fix: render mermaid text in the same font mermaid measures
+   with, so every box fits by construction. (Scoped to diagrams only — the rest
+   of the page keeps the brand font.) */
+#content .mermaid,
+#content .mermaid span,
+#content .mermaid p,
+#content .mermaid div,
+#content .mermaid foreignObject,
+#content .mermaid text,
+#content .mermaid .nodeLabel,
+#content .mermaid .edgeLabel,
+#content .mermaid .cluster-label {
+  font-family: "trebuchet ms", verdana, arial, sans-serif !important;
+}
+/* Overview step pills are meant to stay on a single line (their spaces are
+   non-breaking) — keep them from wrapping. */
+#content .mermaid .node.clickable .nodeLabel,
+#content .mermaid .node.clickable foreignObject,
+#content .mermaid .node.clickable foreignObject > div {
+  white-space: nowrap !important;
+}
+/* Nodes with a mermaid `click` link: a subtle, minimalist hover cue — a slight
+   scale-up from the node's own center, nothing imposing. */
+#content .mermaid .node.clickable {
+  cursor: pointer;
+  transform-box: fill-box;
+  transform-origin: center;
+  transition: transform 120ms ease;
+}
+#content .mermaid .node.clickable:hover {
+  transform: scale(1.05);
+}
+
+/* ── Two-column guide layout (textbook margin) ─────────────────────────────
+   A per-step row: the explanation on the left stays the center of attention,
+   with a quiet margin on the right for supporting code, tables, diagrams, and
+   notes. The split engages at ≥1024px (matching the wide reading column) and
+   stacks into a single column below that, so each visual drops under the text it
+   belongs to. The text column is intentionally narrower than the visual column
+   (4:6) so code and diagrams get room to breathe. */
+@media (min-width: 1024px) {
+  #content .guide-row {
+    display: grid;
+    grid-template-columns: minmax(0, 4fr) minmax(0, 6fr);
+    gap: 2.75rem;
+    align-items: start;
+    margin: 1.5rem 0;
+  }
+  #content .guide-aside {
+    border-left: 1px solid #e5e5e5;
+    padding-left: 1.5rem;
+    font-size: 0.9em;
+  }
+  .dark #content .guide-aside {
+    border-left-color: rgba(255, 255, 255, 0.1);
+  }
+}
+/* Small uppercase caption above a margin visual. */
+#content .aside-label {
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-size: 0.7rem;
+  font-weight: 600;
+  color: #8a8a8a;
+  margin-bottom: 0.5rem;
+}
+/* Margin tables/code shrink to fit the narrow column without forcing a scrollbar. */
+#content .guide-aside table {
+  width: 100%;
+  font-size: 0.8em;
+}
+#content .guide-aside th,
+#content .guide-aside td {
+  padding: 0.4rem 0.6rem;
+}
+
+/* ── File tree ──────────────────────────────────────────────────────────────
+   A clean directory listing (à la a file explorer): a bordered, rounded box
+   matching the card/code-block hairline language, with monospace entries, quiet
+   connector glyphs, and muted inline notes aligned in their own column. Each
+   row is a 2-column grid (name | note) so every note lines up regardless of
+   filename length. */
+#content .filetree {
+  border: 1px solid #e5e5e5;
+  border-radius: 12px;
+  background: #fafafa;
+  padding: 1rem 1.25rem;
+  margin: 1.25rem 0;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, "Cascadia Code", monospace;
+  font-size: 0.85rem;
+  line-height: 1.85;
+}
+.dark #content .filetree {
+  border-color: rgba(255, 255, 255, 0.1);
+  background: rgba(255, 255, 255, 0.03);
+}
+#content .filetree .ft-root {
+  font-weight: 600;
+  color: var(--tw-prose-headings);
+  margin-bottom: 0.15rem;
+}
+#content .filetree .ft-row {
+  display: grid;
+  grid-template-columns: max-content 1fr;
+  gap: 0.5rem 1.5rem;
+  align-items: baseline;
+}
+#content .filetree .ft-branch {
+  color: #c0c0c0;
+}
+.dark #content .filetree .ft-branch {
+  color: #5a5a5a;
+}
+#content .filetree .ft-name {
+  color: var(--tw-prose-headings);
+  font-weight: 500;
+}
+#content .filetree .ft-note {
+  color: #8a8a8a;
+  font-family: "Inter", ui-sans-serif, system-ui, sans-serif;
+  font-size: 0.92em;
+}

From 211910dad128e3eecbfafdfd9fa5b83b2619ba40 Mon Sep 17 00:00:00 2001
From: lukass16 <lukasskellijs@gmail.com>
Date: Wed, 24 Jun 2026 18:58:37 -0700
Subject: [PATCH 08/16] docs(v6): rework creating-an-environment guide and
 rename eval page

Restructure the env.py walkthrough around a workspace-backed counter example
with numbered double-pane parts for the environment, capabilities, lifecycle
hooks, and tasks. Add platform caveats, key requirements, and a hud serve note,
and rename the eval guide page title to "Evaluating Agents".

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/custom.css                            |  29 +--
 docs/v6/guides/creating-an-environment.mdx | 260 ++++++++++++++-------
 docs/v6/guides/running-an-eval.mdx         | 162 +++++++------
 3 files changed, 271 insertions(+), 180 deletions(-)

diff --git a/docs/custom.css b/docs/custom.css
index c0c76b30..b9dd9aaa 100644
--- a/docs/custom.css
+++ b/docs/custom.css
@@ -447,31 +447,22 @@ div:has(> ul.sidebar-group > li[data-group-tag]) > .sidebar-group-header {
   display: none !important;
 }
 
-/* ── Mermaid diagrams: stop labels overflowing their boxes ──────────────────
-   Mermaid measures each node box using its *default* font (trebuchet ms), but
-   the page then inherits the wider HUD brand font (Inter), so the rendered
-   text no longer fits the box it was sized for and the last letters clip. The
-   simple, root-cause fix: render mermaid text in the same font mermaid measures
-   with, so every box fits by construction. (Scoped to diagrams only — the rest
-   of the page keeps the brand font.) */
+/* ── Mermaid diagrams: fix clipped labels at the source ─────────────────────
+   Mermaid measures each node's width with its own font (trebuchet) but the
+   page otherwise renders the labels in the wider HUD brand font (Inter), so
+   the boxes come out too narrow and the last letters get clipped. Instead of
+   patching the overflow, render the labels in the SAME font mermaid measures
+   with — then every box is sized correctly and nothing overflows. */
 #content .mermaid,
+#content .mermaid .nodeLabel,
+#content .mermaid .edgeLabel,
+#content .mermaid .cluster-label,
 #content .mermaid span,
 #content .mermaid p,
 #content .mermaid div,
-#content .mermaid foreignObject,
-#content .mermaid text,
-#content .mermaid .nodeLabel,
-#content .mermaid .edgeLabel,
-#content .mermaid .cluster-label {
+#content .mermaid text {
   font-family: "trebuchet ms", verdana, arial, sans-serif !important;
 }
-/* Overview step pills are meant to stay on a single line (their spaces are
-   non-breaking) — keep them from wrapping. */
-#content .mermaid .node.clickable .nodeLabel,
-#content .mermaid .node.clickable foreignObject,
-#content .mermaid .node.clickable foreignObject > div {
-  white-space: nowrap !important;
-}
 /* Nodes with a mermaid `click` link: a subtle, minimalist hover cue — a slight
    scale-up from the node's own center, nothing imposing. */
 #content .mermaid .node.clickable {
diff --git a/docs/v6/guides/creating-an-environment.mdx b/docs/v6/guides/creating-an-environment.mdx
index 6a01d587..fa35e19f 100644
--- a/docs/v6/guides/creating-an-environment.mdx
+++ b/docs/v6/guides/creating-an-environment.mdx
@@ -7,7 +7,7 @@ mode: "wide"
 
 
 This guide outlines how to create an environment in the HUD format - defining the `env.py` file, registering tasks
-and capabiltiies, doing quick local tests, and deploying the environment to our platform.
+and capabilities, doing quick local tests, and deploying the environment to our platform.
 
 ## Start
 
@@ -30,129 +30,209 @@ Inside the blank template `my-env` you now have four files, each with one job:
 
 ## The `env.py` file
 
-`env.py` is the only file that defines behavior. Here is a complete one: an environment that gives the
-agent a calculator tool, asks it to add two numbers, and scores the answer. We'll take it part by part,
-top to bottom.
+`env.py` is the only file that defines behavior. In this section we'll go through each part of a full example (see it in full below).
+It's an environment that gives the agent a sandboxed shell and file system, asks it to count a letter in a sentence, and scores the answer.
 
-<Accordion title="Full env.py">
+<Accordion title="Full env.py example">
 
-```python env.py
-import asyncio
-
-from fastmcp import FastMCP
+We'll use the following `env.py` example in this section 
 
-from hud.capabilities import Capability
+```python env.py
+from pathlib import Path
 from hud.environment import Environment
 
-server = FastMCP(name="calc-tools")
-
-@server.tool
-def add(a: int, b: int) -> int:
-    """Add two integers."""
-    return a + b
-
-env = Environment(name="calc")
-_server_task: asyncio.Task | None = None
+ROOT = Path("workspace")
+env = Environment(name="counter")
+env.workspace(ROOT)
 
 @env.initialize
-async def _up():
-    global _server_task
-    if _server_task is None:
-        _server_task = asyncio.create_task(
-            server.run_async(transport="http", host="127.0.0.1", port=8040)
-        )
-        await asyncio.sleep(1.0)   # wait until the server is listening
-    env.add_capability(Capability.mcp(name="tools", url="http://127.0.0.1:8040/mcp"))
+async def _setup():
+    (ROOT / "instructions.txt").write_text("Count letters case-insensitively.\n")
 
 @env.shutdown
-async def _down():
-    global _server_task
-    if _server_task is not None:
-        _server_task.cancel()
-        _server_task = None
-
-@env.template(id="sum")
-async def sum_task(a: int, b: int):
-    answer = yield f"Use your tools to compute {a} + {b}. Reply with just the number."
-    yield 1.0 if str(a + b) in (answer or "") else 0.0
+async def _teardown():
+    (ROOT / "instructions.txt").unlink(missing_ok=True)
+
+@env.template(id="count")
+async def count(sentence: str, letter: str):
+    answer = yield f"How many times does '{letter}' appear in '{sentence}'?"
+    yield 1.0 if str(sentence.lower().count(letter.lower())) in (answer or "") else 0.0
 ```
 
 </Accordion>
 
+<div className="guide-row">
+<div className="guide-main">
+
+<div className="part-label">1 · Imports and the environment object</div>
+
+`env = Environment(name="counter")` creates the environment - the central object everything else
+attaches to. Capabilities, lifecycle hooks, and tasks all register against `env`; it holds nothing on
+its own. The `name` identifies it - how a task finds its way back to this definition, and what it's
+published under when you deploy.
+
+</div>
+<div className="guide-aside">
+
+<p className="aside-label">env.py</p>
+
+```python
+from pathlib import Path
+from hud.environment import Environment
+
+ROOT = Path("workspace")
+env = Environment(name="counter")
+```
+
+</div>
+</div>
+
+<div className="guide-row">
+<div className="guide-main">
+
+<div className="part-label">2 · Capabilities</div>
+
+`env.workspace(ROOT)` attaches a **capability**: a sandboxed shell and file system the agent reaches
+over `ssh`, rooted at the `workspace/` directory next to `env.py`. 
+
+</div>
+<div className="guide-aside">
+
+<p className="aside-label">env.py</p>
+
 ```python
-env = Environment(name="calc")
+env.workspace(ROOT)
 ```
 
-This creates the **`Environment` object**. It holds nothing on its own; it's the handle you register
-everything else against. Every capability and task that follows attaches to `env`. The `name` is how a
-task row later finds its way back to this definition. When HUD runs the environment, it imports the
-file, finds this object, and serves whatever is registered on it, which is why the same `env.py` runs
-on your laptop, in a container, or on the platform unchanged.
+</div>
+</div>
 
 ## Capabilities
 
-A **capability** is a connection the agent drives. This environment serves its own: a
-[FastMCP](https://gofastmcp.com) server exposing one tool, `add`. Three things happen, in order, inside
-the lifecycle hooks:
+A **capability** is a connection the agent drives, and it's what keeps an environment portable: you
+declare the connection, and any agent that speaks the protocol drives it with its own tools.
+
+Above, `env.workspace(ROOT)` attached a single `ssh` capability - the common case. An environment isn't
+limited to one, though: publish as many as the tasks need, and the agent sees every one. You attach them
+three ways:
+
+- in the `Environment(...)` constructor, for a service that already exists,
+- with `env.workspace(root)`, the one-line shortcut for the typical shell case above,
+- with `env.add_capability(...)` from a hook, for a service the environment runs itself.
+
+That last form is how you expose a custom tool. A [FastMCP](https://gofastmcp.com) server is a common
+choice: an `@env.initialize` hook starts it, waits for it to bind, then publishes its address.
 
 ```python
-@env.initialize          # runs once before the env accepts any connection
-async def _up():
-    # 1. start the tool server in the background
-    _server_task = asyncio.create_task(server.run_async(transport="http", host="127.0.0.1", port=8040))
-    await asyncio.sleep(1.0)                                  # 2. wait until it's listening
-    env.add_capability(Capability.mcp(name="tools",          # 3. publish its address
+@env.initialize
+async def _start():
+    asyncio.create_task(server.run_http_async(host="127.0.0.1", port=8040))   # 1. start the server
+    await asyncio.sleep(0.2)                                                   # 2. let it bind
+    env.add_capability(Capability.mcp(name="tools",                           # 3. publish its address
                                       url="http://127.0.0.1:8040/mcp"))
+```
 
-@env.shutdown            # runs on shutdown
-async def _down():
-    _server_task.cancel()                                    # tear it down with the env
+Other protocols - a browser over `cdp`, a full desktop over `rfb`, a robot loop - attach the same way.
+The [capabilities](/v6/reference/capabilities) page has the spin-up for each, and the
+[protocol](/v6/advanced/protocol) covers how an agent discovers them over the wire.
+
+<div className="guide-row">
+<div className="guide-main">
+
+<div className="part-label">3 · Lifecycle hooks</div>
+
+`@env.initialize` runs once before the env serves - the place to seed files or start services - and
+`@env.shutdown` runs on teardown, after the run finishes, to release them. Both are optional; here
+they're dummy hooks for demonstration, writing and removing a file.
+
+</div>
+<div className="guide-aside">
+
+<p className="aside-label">env.py</p>
+
+```python
+@env.initialize
+async def _setup():
+    (ROOT / "instructions.txt").write_text("Count letters case-insensitively.\n")
+
+@env.shutdown
+async def _teardown():
+    (ROOT / "instructions.txt").unlink(missing_ok=True)
 ```
 
-`@env.initialize` runs to completion before any agent connects, so by the time one does, the tool is
-live. Step 2 matters: a background task returns before the server has bound its port, and publishing
-the capability too early lets an agent connect to nothing. `@env.shutdown` releases it.
+</div>
+</div>
 
-You attach a capability three ways:
+## Lifecycle hooks
 
-- in the `Environment(...)` constructor, for a service that already exists,
-- with `env.add_capability(...)` from a hook, for a service the environment runs itself (above),
-- with `env.workspace(root)`, the one-line shortcut for the common case: a sandboxed shell over `ssh`.
+When a task needs state - seeded files, a running service, a browser - you bring it up in
+`@env.initialize` and release it in `@env.shutdown`. `@env.initialize` runs once before the env accepts
+any connection, so by the time an agent connects, everything it needs is already in place. Because the
+`env.workspace(...)` hook is registered first, the workspace directory already exists when your own
+hook runs, so you can write straight into `ROOT`.
 
-Other protocols - a browser over `cdp`, a full desktop over `rfb`, a robot loop - attach the same way.
-The [capabilities](/v6/reference/capabilities) page has the spin-up for each.
+Hooks run per environment, not per task, so use them for state every task shares. The [environment
+reference](/v6/reference/environment#lifecycle-hooks-set-up-and-tear-down) covers the full lifecycle.
 
-## Tasks
+<div className="guide-row">
+<div className="guide-main">
+
+<div className="part-label">4 · Tasks</div>
+
+`@env.template(id="count")` defines the task. The first `yield` sends the prompt and pauses; when the
+agent's `answer` arrives the function resumes, and the second `yield` returns the reward - `1.0` if the
+count matches, else `0.0`.
+
+</div>
+<div className="guide-aside">
+
+<p className="aside-label">env.py</p>
 
 ```python
-@env.template(id="sum")
-async def sum_task(a: int, b: int):
-    answer = yield f"Use your tools to compute {a} + {b}. Reply with just the number."
-    yield 1.0 if str(a + b) in (answer or "") else 0.0
+@env.template(id="count")
+async def count(sentence: str, letter: str):
+    answer = yield f"How many times does '{letter}' appear in '{sentence}'?"
+    yield 1.0 if str(sentence.lower().count(letter.lower())) in (answer or "") else 0.0
 ```
 
-A task is an async generator with two `yield`s. The first yields the prompt; the agent then works,
-calling the `add` tool, and its answer comes back into `answer`; the second yields the reward. Whatever
-the agent does happens between the two yields.
+</div>
+</div>
+
+## Tasks
 
-`@env.template()` registers the function as a **template**. Its parameters (`a`, `b`) fill in per run,
-so one definition covers a whole space of tasks. Calling it - `sum_task(a=2, b=3)` - binds one runnable
-[task](/v6/reference/tasks).
+A **task** is HUD's unit of evaluation: a prompt the agent attempts and a reward that scores how it did.
+You write one as an async generator with exactly two `yield`s:
+
+1. **The first `yield` returns the prompt** and pauses the function while the agent works in the
+   environment, driving whatever capabilities it was given. Its answer comes back into `answer`.
+2. **The second `yield` returns the score** - a reward from `0.0` to `1.0`. This is where grading goes:
+   compare `answer` inline, or call a [grader](#grading) to judge what the agent left behind.
+
+`@env.template()` registers it as a **template**, not a single task: its parameters fill in per run, so
+one definition describes a whole space of tasks. Calling it - `count(sentence="strawberry",
+letter="r")` - mints one concrete, runnable [task](/v6/reference/tasks).
 
 ## Grading
 
 The second yield is the reward, a number from `0.0` to `1.0`. Here it's plain Python: compare the
-answer to `a + b`. You have three options as tasks grow:
+agent's answer to the count Python computes. You have three options as tasks grow:
 
 | Approach | What it does |
 | --- | --- |
-| Plain Python | Compute the float inline, like above. Comparison helpers (`exact_match`, `numeric_match`, ...) live in `hud.graders`. |
+| Plain Python | Compute the answer inline, like above. Comparison helpers (`exact_match`, `numeric_match`, ...) live in `hud.graders`. |
 | Async graders | `BashGrader` scores a shell command by exit code; `LLMJudgeGrader` scores against rubric criteria. This is how you grade the state the agent left behind - a test passing, a file written. |
 | Composed graders | `combine` runs several at once and weights them into one reward, each subscore visible in the trace. |
 
-Grading the state the agent left behind is usually the most reliable signal. A grader that returns a
-constant invites reward hacking; see [designing tasks](/v6/reference/advice) for what separates good
-work from bad.
+An async grader is an `await`ed call whose result you yield - `BashGrader`, for instance, runs a command
+in the workspace and scores by exit code:
+
+```python
+result = await BashGrader.grade(weight=1.0, command="pytest -q", cwd=str(ROOT))
+yield result.value
+```
+
+The full set lives in the [graders](/v6/reference/graders) reference; see [designing
+tasks](/v6/reference/advice) for what separates good rewards from hackable ones.
 
 ## Listing tasks in `tasks.py`
 
@@ -160,11 +240,11 @@ work from bad.
 with real arguments:
 
 ```python tasks.py
-from env import sum_task
+from env import count
 
 tasks = [
-    sum_task(a=2, b=3),
-    sum_task(a=10, b=15),
+    count(sentence="strawberry", letter="r"),
+    count(sentence="banana", letter="a"),
 ]
 ```
 
@@ -179,7 +259,17 @@ task, and prints the reward:
 hud eval tasks.py claude
 ```
 
-That's the whole local loop - no API key, no Docker, no separate server. Use it while iterating.
+No Docker or separate server needed - the only thing you need is a provider key for the model
+(`ANTHROPIC_API_KEY`, ...), or a `HUD_API_KEY` to route through the HUD gateway instead.
+
+<Note>
+Runs on macOS, Windows, and Linux, but `ssh` sandbox isolation is **Linux-only** and `BashGrader` needs
+bash (scores `0.0` on native Windows). Off Linux, get full behavior via `--runtime hud`
+(see next guide for running), WSL2, or the built image (`Dockerfile.hud`).
+</Note>
+
+`hud eval` spawns a fresh env per run; to keep one serving locally for repeated runs or manual
+inspection, use `hud serve`.
 
 ## Deploying to the platform
 
@@ -205,4 +295,4 @@ hud sync env              # sync environment metadata
 
 Your environment now lives on the platform, ready to run at scale and compare across models. Running
 those evaluations - locally, on a cloud sandbox, or on the platform - is covered in
-[evaluating agents](/v6/guides/running-an-eval).
+[](/v6/guides/running-an-eval).
diff --git a/docs/v6/guides/running-an-eval.mdx b/docs/v6/guides/running-an-eval.mdx
index ac61dbeb..11193bf9 100644
--- a/docs/v6/guides/running-an-eval.mdx
+++ b/docs/v6/guides/running-an-eval.mdx
@@ -1,105 +1,126 @@
 ---
-title: "Running an Eval"
-description: "Run an agent against your tasks - from the platform or from a local environment - and read the reward."
+title: "Evaluating Agents"
+description: "Point an agent at a set of tasks, choose where each rollout runs, and read the reward."
 icon: "play"
+mode: "wide"
 ---
 
-`hud eval` is the central command for all evaluations. It works whether your environment lives on the HUD platform or in a local `env.py`, and every rollout it produces lands as a traced, replayable entry in your [platform dashboard](https://hud.ai). The mechanics underneath - the control channel, `tasks.start`, `tasks.grade` - are documented in [Protocol](/v6/advanced/protocol).
 
-The two workflows differ only in where your environment lives:
+This guide outlines how to run an evaluation: pointing an agent at a set of tasks, choosing where each
+rollout runs, and reading the reward. One command sits at the center of every eval - `hud eval` - and it
+works the same whether your environment is deployed to the platform or lives in a local `env.py`. Every
+rollout it produces is traced to your [dashboard](https://hud.ai), and the messages an agent and an
+environment exchange underneath are covered in [protocol](/v6/advanced/protocol).
 
-| | When to use | Entry points |
+There are two workflows, and they differ only in where the environment lives:
+
+| Workflow | When to use it | Where you start it |
 | --- | --- | --- |
-| [**Deployed environment**](#deployed-environment) | Env is built and hosted on HUD | Terminal or platform UI |
-| [**Local environment**](#local-environment) | `env.py` is on your disk | Terminal or run script |
+| [Deployed environment](#running-a-deployed-environment) | The env is built and hosted on the platform | Terminal or platform |
+| [Local environment](#running-a-local-environment) | The `env.py` is on your disk | Terminal or run script |
 
----
+## Running a deployed environment
 
-## Deployed environment
+A **deployed environment** has been built and published to the platform with
+[`hud deploy`](/v6/guides/creating-an-environment#deploying-to-the-platform), or is one you picked from
+the [catalog](https://hud.ai/environments/new). It runs entirely on hosted infra, so there's no local
+process to manage - you start a run from the terminal or from the platform, and both trace to the same
+place.
 
-A **deployed environment** is one that has been built and published to HUD with [`hud deploy`](/v6/guides/creating-an-environment#deploy-it), or an existing environment from the [platform catalog](https://hud.ai/environments/new). The environment runs entirely on HUD's hosted infra - there is no local process to manage.
+<div className="guide-row">
+<div className="guide-main">
 
-Two entry points are available, and both trace to the same dashboard.
+**From the terminal**, pass the taskset name or id to `hud eval`. The tasks are fetched from the
+platform and each rollout runs remotely on hosted infra.
 
-**From the terminal.** Pass the taskset name or id to `hud eval`. The tasks are fetched from the platform and each rollout runs remotely on HUD's infra:
+**From the platform**, open [hud.ai](https://hud.ai), pick the environment, choose a taskset and a
+model, and launch - no CLI required.
+
+</div>
+<div className="guide-aside">
+
+<p className="aside-label">terminal</p>
 
 ```bash
 hud eval "My Taskset" claude
 hud eval "My Taskset" claude --all --group 3
 ```
 
-**From the platform.** Open [hud.ai](https://hud.ai), select your environment, choose a taskset and a model, and launch from the dashboard. No CLI required.
+</div>
+</div>
 
 ### Choosing an agent
 
-The agent shorthand (`claude`, `openai`, `gemini`) selects a built-in harness and routes LLM calls through the [HUD gateway](/v6/reference/agents) - a single `HUD_API_KEY` covers every provider, so switching models is one flag:
+The agent name (`claude`, `openai`, `gemini`) selects a built-in harness and routes calls through the
+[HUD gateway](/v6/reference/agents), where one `HUD_API_KEY` covers every provider. Switching models is a
+single flag, and `hud models list` shows every model the gateway knows.
 
 ```bash
-hud eval "My Taskset" claude --model claude-haiku-4-5   # cheaper model for fast iteration
+hud eval "My Taskset" claude --model claude-haiku-4-5   # a cheaper model for fast iteration
 hud eval "My Taskset" openai --model gpt-5
 hud eval "My Taskset" gemini
 ```
 
-To see every model the gateway supports, run `hud models list`. For a custom harness - a fine-tuned model, a framework you already use - see [Bring your own harness](/v6/advanced/extending#bring-your-own-harness).
+For a custom loop - a fine-tuned model, a framework you already use - see
+[bring your own harness](/v6/advanced/extending#bring-your-own-harness).
 
-### Traces and results
+### Reading traces and results
 
-Each rollout is a **trace**: a replayable timeline of every action the agent took and the reward it received. All traces are visible on the [HUD dashboard](https://hud.ai), grouped into a **job**. You can also inspect them from the CLI:
+Each rollout is a **trace**: a replayable timeline of everything the agent did and the reward it earned.
+Traces are grouped into a **job** and shown on the [dashboard](https://hud.ai). You can also read them
+from the terminal:
 
 ```bash
 hud jobs               # recent jobs - id, name, taskset, status
-hud jobs <job-id>      # traces for that job
-hud trace <trace-id>   # one rollout in full
+hud jobs <job-id>      # the traces in one job
+hud trace <trace-id>   # a single rollout in full
 ```
 
----
-
-## Local environment
-
-A local environment is an `env.py` on your disk. This is the typical workflow during environment development. `hud eval` is the preferred entry point; a run script gives you programmatic control when you need it.
+## Running a local environment
 
-Both paths accept a [runtime](/v6/reference/runtime) - the one argument that decides where each rollout runs. The environment definition never changes; only the runtime changes.
+A local environment is an `env.py` on your disk - the usual case while you're still developing it.
+`hud eval` is the way to run it; a run script is the same eval in Python when you want programmatic
+control. Both take a [runtime](/v6/reference/runtime), the one argument that decides where each rollout
+runs. The environment definition never changes - only the runtime does.
 
 <Note>
-With a `HUD_API_KEY` set, local evals also trace to the [platform dashboard](https://hud.ai). Without one, rollouts run and grade locally with no platform calls.
+With a `HUD_API_KEY` set, local runs still trace to the [dashboard](https://hud.ai). Without one, they
+run and grade entirely on your machine with no platform calls.
 </Note>
 
-### Using `hud eval`
+### With `hud eval`
 
-`hud eval` is the preferred local iteration loop. It spawns the env subprocess automatically - you do not need `hud serve` running, a Docker daemon, or a HUD API key for a purely local run.
+`hud eval` spawns the env subprocess for you, so a purely local run needs no `hud serve`, no Docker, and
+no API key. Point it at your task source, pass an agent name, and set `--runtime` when you want a rollout
+to run somewhere other than your machine.
 
 <div className="guide-row">
 <div className="guide-main">
 
-Point `hud eval` at your task source and pass an agent name. By default, each rollout runs in a local child process from your `env.py`:
-
-```bash
-hud eval tasks.py claude                             # first task, one rollout
-hud eval tasks.py claude --all                       # every task
-hud eval tasks.py claude --group 3                   # 3 rollouts per task
-hud eval tasks.py claude --runtime hud               # run on HUD's hosted infra
-hud eval tasks.py claude --runtime tcp://host:8765   # attach to a running substrate
-```
-
-The `--runtime` flag sets where each rollout executes. Omit it for the fastest local loop. For the full flag set, see [`hud eval`](/v6/reference/cli#hud-eval).
+By default each rollout runs in a child process from your `env.py`. The `--runtime` flag moves that
+placement elsewhere without touching the environment. See [`hud eval`](/v6/reference/cli#hud-eval) for the
+full flag set.
 
 </div>
 <div className="guide-aside">
 
-<p className="aside-label">--runtime options</p>
+<p className="aside-label">terminal</p>
 
-| `--runtime` | Where the env runs | Requires |
-| --- | --- | --- |
-| *(omitted)* | Child process on your machine | Nothing |
-| `hud` | HUD's hosted infra | `hud deploy` first |
-| `tcp://host:port` | A substrate you already started | A running server |
+```bash
+hud eval tasks.py claude               # first task, one rollout
+hud eval tasks.py claude --all         # every task
+hud eval tasks.py claude --group 3     # 3 rollouts per task
+hud eval tasks.py claude --runtime hud # on hosted infra
+```
 
 </div>
 </div>
 
-### Using a run script
+### With a run script
 
-When you want programmatic control - looping over agents, integrating into a training pipeline, or routing tasks to different infra - call `taskset.run` directly and pass a [runtime](/v6/reference/runtime) object:
+When you want programmatic control - looping over agents, feeding a training pipeline, routing tasks to
+different infra - call `taskset.run` directly and hand it a [runtime](/v6/reference/runtime) object. This
+is the same eval `hud eval` runs, written out in Python.
 
 ```python run.py
 import asyncio
@@ -116,45 +137,34 @@ async def main():
 asyncio.run(main())
 ```
 
-Swap the runtime to change where the env runs without touching `env.py` or the tasks:
+The runtime is where you set placement. Swap it for another and the env runs somewhere else, with no
+change to `env.py` or the tasks:
 
 | Runtime | Where the env runs |
 | --- | --- |
-| `LocalRuntime("env.py")` | Child process on your machine |
-| `DockerRuntime("my-env")` | Fresh local container per rollout |
-| `ModalRuntime("my-env")` | Fresh [Modal](https://modal.com) sandbox per rollout |
-| `DaytonaRuntime("my-env")` | Fresh [Daytona](https://daytona.io) sandbox per rollout |
-| `HUDRuntime()` | HUD's hosted infra (after `hud deploy`) |
+| `LocalRuntime("env.py")` | A child process on your machine |
+| `DockerRuntime("my-env")` | A fresh local container per rollout |
+| `ModalRuntime("my-env")` | A fresh [Modal](https://modal.com) sandbox per rollout |
+| `DaytonaRuntime("my-env")` | A fresh [Daytona](https://daytona.io) sandbox per rollout |
+| `HUDRuntime()` | Hosted infra, after `hud deploy` |
 | `Runtime("tcp://host:port")` | A substrate you started yourself |
 
-For constructor details and how to bring your own runtime, see [Runtime](/v6/reference/runtime).
+The [runtime reference](/v6/reference/runtime) covers each constructor and how to bring your own.
 
-### `hud serve`
+### Serving an environment directly
 
-`hud eval` starts and stops the env subprocess automatically. `hud serve` exposes the same control channel as a standalone long-lived process - useful when you want to talk to a running env directly from a script, test a packaged image manually, or drive `hud task start` and `hud task grade` by hand:
+`hud eval` starts and stops the env subprocess for you. `hud serve` instead exposes the same control
+channel as a standalone, long-lived process - useful for talking to a running env from a script, testing
+a packaged image by hand, or driving `hud task start` and `hud task grade` yourself.
 
 ```bash
 hud serve            # auto-detect env.py, bind :8765
 hud serve env.py -p 9000
 ```
 
-From a script, attach with `Runtime("tcp://localhost:8765")`; from `hud eval`, pass `--runtime tcp://localhost:8765`. The [Protocol reference](/v6/advanced/protocol) documents every message the control channel speaks.
-
----
+Attach to it from a script with `Runtime("tcp://localhost:8765")`, or from `hud eval` with
+`--runtime tcp://localhost:8765`. The [protocol reference](/v6/advanced/protocol) describes every message
+the channel speaks.
 
-## Where to go next
-
-<CardGroup cols={2}>
-<Card title="Deploying an environment" icon="rocket" href="/v6/guides/creating-an-environment#deploy-it">
-  Build your env into a platform image with `hud deploy`.
-</Card>
-<Card title="Runtimes" icon="server" href="/v6/reference/runtime">
-  Every built-in runtime and how to bring your own.
-</Card>
-<Card title="Agents" icon="robot" href="/v6/reference/agents">
-  Swap the model with a string, or bring your own harness.
-</Card>
-<Card title="Protocol" icon="route" href="/v6/advanced/protocol">
-  How an agent and an environment communicate.
-</Card>
-</CardGroup>
+With runs in hand, turn the reward spread into model updates - covered in
+[training agents](/v6/guides/training-models).

From 8d709a1c4c4516363cc7627b84694080113b9ce2 Mon Sep 17 00:00:00 2001
From: lukass16 <lukasskellijs@gmail.com>
Date: Wed, 24 Jun 2026 19:12:23 -0700
Subject: [PATCH 09/16] docs(v6): restyle running-an-eval guide to match
 creating-an-environment

Align the evaluation guide with the house style: wide mode, a plain
opener, verb-phrase section titles, lowercase link text, and a prose
closer instead of a CardGroup. Flatten the unbalanced two-column split,
drop the section dividers, standardize on "platform" over "dashboard",
and remove the reference to the not-yet-live environment catalog.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/v6/guides/running-an-eval.mdx | 46 +++++++++++-------------------
 1 file changed, 17 insertions(+), 29 deletions(-)

diff --git a/docs/v6/guides/running-an-eval.mdx b/docs/v6/guides/running-an-eval.mdx
index 11193bf9..ad7a2187 100644
--- a/docs/v6/guides/running-an-eval.mdx
+++ b/docs/v6/guides/running-an-eval.mdx
@@ -6,11 +6,10 @@ mode: "wide"
 ---
 
 
-This guide outlines how to run an evaluation: pointing an agent at a set of tasks, choosing where each
-rollout runs, and reading the reward. One command sits at the center of every eval - `hud eval` - and it
-works the same whether your environment is deployed to the platform or lives in a local `env.py`. Every
-rollout it produces is traced to your [dashboard](https://hud.ai), and the messages an agent and an
-environment exchange underneath are covered in [protocol](/v6/advanced/protocol).
+This guide outlines how to run an evaluation: pointing an agent at tasks, choosing where each rollout
+runs, and reading the reward. The `hud eval` command is the centra tool for evals: it drives
+every eval and works the same whether your environment is deployed or a local `env.py`. Every rollout
+traces to your [platform](https://hud.ai).
 
 There are two workflows, and they differ only in where the environment lives:
 
@@ -22,32 +21,20 @@ There are two workflows, and they differ only in where the environment lives:
 ## Running a deployed environment
 
 A **deployed environment** has been built and published to the platform with
-[`hud deploy`](/v6/guides/creating-an-environment#deploying-to-the-platform), or is one you picked from
-the [catalog](https://hud.ai/environments/new). It runs entirely on hosted infra, so there's no local
-process to manage - you start a run from the terminal or from the platform, and both trace to the same
-place.
+[`hud deploy`](/v6/guides/creating-an-environment#deploying-to-the-platform). It runs entirely on hosted
+infra, so there's no local process to manage - you start a run from the terminal or from the platform,
+and both trace to the same place.
 
-<div className="guide-row">
-<div className="guide-main">
-
-**From the terminal**, pass the taskset name or id to `hud eval`. The tasks are fetched from the
-platform and each rollout runs remotely on hosted infra.
-
-**From the platform**, open [hud.ai](https://hud.ai), pick the environment, choose a taskset and a
-model, and launch - no CLI required.
-
-</div>
-<div className="guide-aside">
-
-<p className="aside-label">terminal</p>
+**From the terminal**, pass the taskset name or id to `hud eval`. The tasks are fetched from the platform
+and each rollout runs remotely on hosted infra.
 
 ```bash
 hud eval "My Taskset" claude
 hud eval "My Taskset" claude --all --group 3
 ```
 
-</div>
-</div>
+**From the platform**, open [hud.ai](https://hud.ai), pick the environment, choose a taskset and a model,
+and launch - no CLI required.
 
 ### Choosing an agent
 
@@ -67,7 +54,7 @@ For a custom loop - a fine-tuned model, a framework you already use - see
 ### Reading traces and results
 
 Each rollout is a **trace**: a replayable timeline of everything the agent did and the reward it earned.
-Traces are grouped into a **job** and shown on the [dashboard](https://hud.ai). You can also read them
+Traces are grouped into a **job** and shown on the [platform](https://hud.ai). You can also read them
 from the terminal:
 
 ```bash
@@ -79,12 +66,13 @@ hud trace <trace-id>   # a single rollout in full
 ## Running a local environment
 
 A local environment is an `env.py` on your disk - the usual case while you're still developing it.
-`hud eval` is the way to run it; a run script is the same eval in Python when you want programmatic
+`hud eval` is the way to run it; alternatively you can write your own run script 
+that calls `Taskset.run` the same way when you want programmatic
 control. Both take a [runtime](/v6/reference/runtime), the one argument that decides where each rollout
 runs. The environment definition never changes - only the runtime does.
 
 <Note>
-With a `HUD_API_KEY` set, local runs still trace to the [dashboard](https://hud.ai). Without one, they
+With a `HUD_API_KEY` set, local runs still trace to the [platform](https://hud.ai). Without one, they
 run and grade entirely on your machine with no platform calls.
 </Note>
 
@@ -119,7 +107,7 @@ hud eval tasks.py claude --runtime hud # on hosted infra
 ### With a run script
 
 When you want programmatic control - looping over agents, feeding a training pipeline, routing tasks to
-different infra - call `taskset.run` directly and hand it a [runtime](/v6/reference/runtime) object. This
+different infra - call `Taskset.run` directly and hand it a [runtime](/v6/reference/runtime) object. This
 is the same eval `hud eval` runs, written out in Python.
 
 ```python run.py
@@ -167,4 +155,4 @@ Attach to it from a script with `Runtime("tcp://localhost:8765")`, or from `hud
 the channel speaks.
 
 With runs in hand, turn the reward spread into model updates - covered in
-[training agents](/v6/guides/training-models).
+[training agents](/v6/guides/training-agents).

From 605354cec4776c3d5f1956ff90b094f2f842dc10 Mon Sep 17 00:00:00 2001
From: lukass16 <lukasskellijs@gmail.com>
Date: Wed, 24 Jun 2026 19:39:00 -0700
Subject: [PATCH 10/16] docs(v6): rewrite training guide and remove
 split-layout demo

Rename the training-models guide to training-agents and rewrite it in the
style of the creating-an-environment and running-an-eval guides: a four-step
loop, a double-pane train.py walkthrough, and group/checkpoint sections, with
deeper API detail left to the training reference.

Add a scoped step-list CSS class for compact lists in split panes that keeps
standard line spacing without the negative-margin overlap of tight-list.

Delete the split-layout demo page and its navigation entry.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/custom.css                      |  21 ++++
 docs/docs.json                       |   2 +-
 docs/v6/guides/split-layout-demo.mdx |  88 --------------
 docs/v6/guides/training-agents.mdx   | 172 +++++++++++++++++++++++++++
 docs/v6/guides/training-models.mdx   |  51 --------
 5 files changed, 194 insertions(+), 140 deletions(-)
 delete mode 100644 docs/v6/guides/split-layout-demo.mdx
 create mode 100644 docs/v6/guides/training-agents.mdx
 delete mode 100644 docs/v6/guides/training-models.mdx

diff --git a/docs/custom.css b/docs/custom.css
index b9dd9aaa..929c4772 100644
--- a/docs/custom.css
+++ b/docs/custom.css
@@ -197,6 +197,27 @@ body::after {
   margin-bottom: 0 !important;
 }
 
+/* Step list: standard line spacing (no tight pull), with a gentle top margin so
+   it never overlaps a wrapping intro line above it (used in the split guide panes). */
+#content .step-list ul,
+#content .step-list ol {
+  margin-top: 0.4rem !important;
+  margin-bottom: 0.4rem !important;
+}
+#content .step-list li {
+  margin-top: 0.5rem !important;
+  margin-bottom: 0.5rem !important;
+  line-height: 1.7 !important;
+}
+#content .step-list li > p {
+  margin-top: 0 !important;
+  margin-bottom: 0 !important;
+}
+/* breathing room before a part-label that follows a step list (e.g. "2 · ...") */
+#content .step-list + .part-label {
+  margin-top: 1.6rem !important;
+}
+
 /* Blockquotes: gold left rule, like a pull-quote. */
 #content blockquote {
   border-left: 2px solid #c0960c;
diff --git a/docs/docs.json b/docs/docs.json
index 4a117704..db492c61 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -67,7 +67,7 @@
             "default": true,
             "groups": [
               { "group": "Start here", "pages": ["v6/start/index", "v6/start/quickstart", "v6/start/overview"] },
-              { "group": "Guides", "pages": ["v6/guides/creating-an-environment", "v6/guides/running-an-eval", "v6/guides/training-models", "v6/guides/split-layout-demo"] },
+              { "group": "Guides", "pages": ["v6/guides/creating-an-environment", "v6/guides/running-an-eval", "v6/guides/training-agents"] },
               { "group": "Reference", "pages": ["v6/reference/environment", "v6/reference/tasks", "v6/reference/capabilities", "v6/reference/agents", "v6/reference/runtime", "v6/reference/graders", "v6/reference/training", "v6/reference/types", "v6/reference/cli"] },
               { "group": "Advanced", "pages": [
                 { "group": "Advanced", "expanded": false, "pages": ["v6/advanced/protocol", "v6/advanced/extending", "v6/reference/advice", "v6/advanced/robots", "v6/advanced/harbor-convert"] }
diff --git a/docs/v6/guides/split-layout-demo.mdx b/docs/v6/guides/split-layout-demo.mdx
deleted file mode 100644
index 15325cd8..00000000
--- a/docs/v6/guides/split-layout-demo.mdx
+++ /dev/null
@@ -1,88 +0,0 @@
----
-title: "Split Layout (Demo)"
-description: "A textbook-style two-column layout: explanation on the left, supporting visuals in the margin."
-icon: "table-columns"
----
-
-This page demonstrates a minimal two-column guide layout. The left column holds the explanation and stays
-the center of attention; the right column is a quiet textbook margin for the supporting code, tables,
-diagrams, and notes that belong beside it. On narrow screens the columns stack, so each visual drops under
-the text it belongs to.
-
-<div className="guide-row">
-<div className="guide-main">
-
-### Declare the environment
-
-An environment is defined in a single `env.py`. Start with an `Environment` and at least one capability -
-the connection the agent drives. The fields below are the minimum a runnable environment needs.
-
-</div>
-<div className="guide-aside">
-
-<p className="aside-label">env.py</p>
-
-```python
-from hud.environment import Environment
-from hud.capabilities import Capability
-
-env = Environment(name="my-env", capabilities=[
-    Capability.ssh(name="shell", url="<url>"),
-])
-```
-
-| Field | Role |
-| --- | --- |
-| `name` | identifies the env |
-| `capabilities` | what the agent drives |
-
-</div>
-</div>
-
-<div className="guide-row">
-<div className="guide-main">
-
-### Lifecycle
-
-Optional hooks run setup and teardown around each rollout. Use them only when a task needs fixtures,
-services, or seed state - stateless tasks skip them entirely.
-
-</div>
-<div className="guide-aside">
-
-<p className="aside-label">lifecycle</p>
-
-```mermaid
-flowchart TB
-    I["initialize"] --> S["serve task"] --> D["shutdown"]
-    classDef n fill:#efece8,stroke:#2b2722,color:#2b2722;
-    class I,S,D n;
-```
-
-</div>
-</div>
-
-<div className="guide-row">
-<div className="guide-main">
-
-### Grade a task
-
-A task prompts the agent and returns a reward. The final `yield` is the score - that number, with the
-trace, is what you read in an eval and feed into training.
-
-</div>
-<div className="guide-aside">
-
-<p className="aside-label">graded task</p>
-
-```python
-@env.template()
-async def task(target: str = "..."):
-    answer = yield f"<prompt {target}>"
-    yield 1.0 if answer == target else 0.0
-```
-
-<Note>The reward is a single number between 0 and 1.</Note>
-
-</div>
-</div>
diff --git a/docs/v6/guides/training-agents.mdx b/docs/v6/guides/training-agents.mdx
new file mode 100644
index 00000000..11f1abf1
--- /dev/null
+++ b/docs/v6/guides/training-agents.mdx
@@ -0,0 +1,172 @@
+---
+title: "Training Agents"
+description: "Turn an evaluation into a training loop: fork a model, roll out a taskset in groups, and feed the rewards back to nudge the weights."
+icon: "dumbbell"
+mode: "wide"
+---
+
+
+This guide outlines how to turn an evaluation into a training loop - forking a model you're allowed to
+update, rolling out a taskset in groups, and feeding the rewards back to move the weights. The rewards
+you already collect are the training signal, so training reuses the eval from the
+[previous guide](/v6/guides/running-an-eval) almost unchanged.
+
+## How training works
+
+Evaluation and training share the same three pieces: a **task**, an **agent**, and a **reward**. An
+eval runs that once; training repeats it, nudging the weights toward higher-reward rollouts after each
+batch. The reward is already the signal - nothing new gets graded.
+
+The loop repeats four steps:
+
+<div className="tight-list">
+
+1. **Roll out** a batch of tasks with the current model.
+2. **Score** each rollout - the reward you already get for free.
+3. **Nudge** the weights toward the rollouts that scored higher.
+4. **Repeat** - the next batch samples the now-improved model.
+
+</div>
+
+Two things have to be true before that loop can learn:
+
+| Prerequisite | Why it matters |
+| --- | --- |
+| A **trainable model** you forked | You can only advance weights you own, so you start by forking a base into a private model (below). |
+| A taskset whose rewards **spread** | Training learns from the gap between rollouts; a task every rollout passes or fails teaches nothing (see [Why groups matter](#why-groups-matter)). |
+
+## Fork a trainable model
+
+A **trainable model** is a gateway model whose weights you're allowed to advance. Only some bases can be
+forked. List the models to see which models are trainable, then fork one into a private, team-owned model.
+
+<div className="guide-row">
+<div className="guide-main">
+
+The `hud models list` command marks forkable bases in its Trainable column. Running `hud models fork`
+copies a base into a new slug you own, starting from the base's current weights, 
+so training continues from there.
+
+</div>
+<div className="guide-aside">
+
+<p className="aside-label">terminal</p>
+
+```bash
+hud models list                               # the Trainable column marks forkable bases
+hud models fork Qwen/Qwen3.5-4B --name arith-rl
+```
+
+</div>
+</div>
+
+The new slug (`arith-rl`) is both what you **sample** and what you **train** - one string flows through
+the whole loop.
+
+## Run the loop
+
+This is the whole thing in Python: each step rolls out a batch with the current weights, hands the
+graded rollouts to the trainer, and the trainer nudges the weights and promotes them - so the next step
+samples an improved model.
+
+<div className="guide-row">
+<div className="guide-main">
+
+<div className="part-label">1 · Set up the agent and trainer</div>
+
+Two objects, both keyed to the model you forked:
+
+<div className="step-list">
+
+- **The agent** rolls out like in an eval. The `return_token_ids` flag marks it a training rollout, so
+  each response carries the token ids and logprobs the trainer needs.
+- **The trainer** advances the weights behind the slug in place. It runs on a
+  [Tinker](https://thinkingmachines.ai/tinker/) client under the hood, so you write no ML infra.
+
+</div>
+
+<div className="part-label">2 · Roll out, then nudge</div>
+
+One job spans the session; each step appends a batch and trains on it:
+
+<div className="step-list">
+
+- **Open the job** with `group=8` - 8 rollouts per task, so the rewards are comparable (next).
+- **Roll out** the batch, the same eval as the [previous guide](/v6/guides/running-an-eval). The
+  [runtime](/v6/reference/runtime) sets where it runs; swap `LocalRuntime` for `HUDRuntime()` unchanged.
+- **Nudge** with `trainer.step` - the one line that learns. It scores each rollout against its group,
+  shifts the weights, then **promotes** them so the gateway serves the new ones at once.
+
+</div>
+
+</div>
+<div className="guide-aside">
+
+<p className="aside-label">train.py</p>
+
+```python
+import asyncio
+from hud import TrainingClient, Taskset, LocalRuntime
+from hud.agents import create_agent
+from hud.eval import Job
+
+MODEL = "arith-rl"   # the model you forked above
+
+# 1 · set up the agent and trainer
+agent = create_agent(MODEL, completion_kwargs={"extra_body": {"return_token_ids": True}})
+trainer = TrainingClient(MODEL)
+taskset = Taskset.from_file("tasks.py")
+
+# 2 · roll out, then nudge
+async def main():
+    session = await Job.start(MODEL, group=8)   # one job spans the session
+    for step in range(10):
+        start = len(session.runs)
+        await taskset.run(agent, runtime=LocalRuntime("env.py"), job=session)
+        batch = session.runs[start:]                          # this step's rollouts
+        await trainer.step(batch, learning_rate=1e-5, group_size=8)   # nudge + promote
+        print(f"step {step}  reward {sum(r.reward for r in batch) / len(batch):.2f}")
+
+asyncio.run(main())
+```
+
+</div>
+</div>
+
+## Why groups matter
+
+By default, HUD trains with **GRPO**, which scores each rollout relative to its group: its advantage is
+`reward - group_mean`. A rollout counts as good only next to its siblings on the same task.
+
+So if every rollout in a group earns the **same** reward, every advantage is zero and nothing moves -
+however high the average looks. That is why each task runs as a group (`group=8`) and why your tasks must
+produce a spread of rewards. Trainability is a property of your tasks, not the loop;
+[designing tasks](/v6/reference/advice) covers how to build that spread in.
+
+## Watch it improve
+
+Each `trainer.step` adds a node to the model's **checkpoint tree** and promotes it to the **head** - the
+weights the gateway now serves. Read the tree from the shell, or the mean reward from the loop's print.
+
+<div className="guide-row">
+<div className="guide-main">
+
+Because every step checkpoints, any node is also a rollback point. Roll the head back when the objective
+changes: if you edit the reward or the environment mid-run, set the head to a checkpoint taken before the
+change so the run measures the new objective from a clean start.
+
+</div>
+<div className="guide-aside">
+
+<p className="aside-label">terminal</p>
+
+```bash
+hud models checkpoints arith-rl       # the checkpoint tree, active head marked
+hud models head arith-rl --set <id>   # roll back or branch from an earlier point
+```
+
+</div>
+</div>
+
+The [training reference](/v6/reference/training) covers the `TrainingClient` API, the built-in and
+custom losses, and the checkpoint tree in full.
diff --git a/docs/v6/guides/training-models.mdx b/docs/v6/guides/training-models.mdx
deleted file mode 100644
index d107fc0a..00000000
--- a/docs/v6/guides/training-models.mdx
+++ /dev/null
@@ -1,51 +0,0 @@
----
-title: "Training Agents"
-description: "Group rollouts per task, read the reward spread, and feed it into your RL loop."
-icon: "dumbbell"
----
-
-Evaluation and training share the same machinery: a task, an agent, and a reward. To train, you run many
-rollouts of the same task, look at how the rewards spread, and use that signal to update the model.
-
-## 1. Group rollouts per task
-
-Run a group of rollouts for each task instead of a single attempt. The spread of rewards within a group
-is the learning signal - a task every rollout passes (or fails) teaches nothing.
-
-```python
-from hud.eval import LocalRuntime
-from tasks import TASKS
-
-job = await TASKS.run(agent, runtime=LocalRuntime("env.py"), group=8)   # 8 rollouts per task
-```
-
-## 2. Read the reward spread
-
-Each group yields a distribution of rewards. A healthy training task has variance - some rollouts succeed,
-some don't - so the policy has a gradient to climb.
-
-```python
-for task_group in job.groups:
-    print(task_group.rewards)        # e.g. [1.0, 0.0, 1.0, 0.0, 1.0, 1.0, 0.0, 1.0]
-```
-
-## 3. Feed it into your RL loop
-
-Hand the grouped rewards straight to your own GRPO/PPO loop, or a stack like
-[Tinker](https://thinkingmachines.ai/tinker/), [slime](https://github.com/THUDM/slime), or
-[Fireworks](https://fireworks.ai/). The environment and reward stay fixed; everything else is yours to
-swap.
-
-## Where to go next
-
-<CardGroup cols={2}>
-<Card title="Training" icon="dumbbell" href="/v6/reference/training">
-  The training reference: groups, rewards, and RL integration.
-</Card>
-<Card title="Evaluating Agents" icon="play" href="/v6/guides/running-an-eval">
-  Form a taskset and run an agent against it.
-</Card>
-<Card title="Designing tasks" icon="signal" href="/v6/reference/advice">
-  Build tasks with the variance that makes training work.
-</Card>
-</CardGroup>

From f3b9c1d3b6207250a39c5907792eb59e53600616 Mon Sep 17 00:00:00 2001
From: lukass16 <lukasskellijs@gmail.com>
Date: Wed, 24 Jun 2026 20:16:06 -0700
Subject: [PATCH 11/16] docs(cookbooks): rewrite for clarity in docs-write
 style

Reframe all five cookbook pages against the docs-write conventions and the
running-an-eval house style, preserving every fact, code block, and See also
group while improving readability.

- index: drop em dashes, motivate cookbooks as worked end-to-end evals
- coding-agent: lead with the mental model, cut "one design point" filler,
  standardize the ssh capability name
- ops-diagnostics: define an investigation task by why it is hard
- a2a-chat: turn the env-var paragraph into a table, define Chat on first use
- robot-benchmark: define bridge/endpoint/contract, fix bare-identifier
  opening, split the dense rollout paragraph into a bold-lead-in list

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/v6/cookbooks/a2a-chat.mdx        | 13 ++++++++++---
 docs/v6/cookbooks/coding-agent.mdx    |  6 +++---
 docs/v6/cookbooks/index.mdx           | 13 +++++++------
 docs/v6/cookbooks/ops-diagnostics.mdx |  4 ++--
 docs/v6/cookbooks/robot-benchmark.mdx | 10 +++++++---
 5 files changed, 29 insertions(+), 17 deletions(-)

diff --git a/docs/v6/cookbooks/a2a-chat.mdx b/docs/v6/cookbooks/a2a-chat.mdx
index 59e7ec2b..64ccff94 100644
--- a/docs/v6/cookbooks/a2a-chat.mdx
+++ b/docs/v6/cookbooks/a2a-chat.mdx
@@ -4,9 +4,9 @@ description: "Build a chat task on the HUD A2A orchestrator, serve it over the a
 icon: "plug"
 ---
 
-A complete, runnable example of putting a wire protocol in front of `Chat`: serve a `messages`-style task as an [A2A](https://github.com/google/a2a) endpoint, so any A2A client - including another LLM using it as a tool - can hold a conversation with your environment.
+Sometimes you want to reach an environment over a standard wire protocol instead of the SDK. This example puts one in front of `Chat`: it serves a `messages`-style task as an [A2A](https://github.com/google/a2a) endpoint, so any A2A client - including another LLM using it as a tool - can hold a conversation with your environment.
 
-`Chat` is protocol-agnostic (see [Chat](/v6/advanced/extending#chat-and-multi-turn)); the A2A layer is a reference server kept outside the SDK on purpose. Copy and adapt it from [`cookbooks/a2a-chat`](https://github.com/hud-evals/hud-python/tree/main/cookbooks/a2a-chat).
+A **`Chat`** is HUD's multi-turn conversation object, and it is protocol-agnostic (see [Chat](/v6/advanced/extending#chat-and-multi-turn)). The A2A layer is a reference server kept outside the SDK on purpose, so you copy and adapt it from [`cookbooks/a2a-chat`](https://github.com/hud-evals/hud-python/tree/main/cookbooks/a2a-chat).
 
 ## The pieces
 
@@ -48,7 +48,14 @@ uv run llm_client.py        # LLM-fronted client
 
 The server publishes an agent card at `/.well-known/agent-card.json` and accepts A2A messages at the root endpoint. Each A2A context gets its own `Chat`, so concurrent conversations stay independent.
 
-Configuration is via env vars: `HUD_MODEL` picks the agent's model (gateway, needs `HUD_API_KEY`), `HUD_TASK`/`HUD_ENV` pick the task row, `HUD_SOURCE` spawns a different env source, and `HUD_ENV_URL` attaches each turn to an already-served control channel (e.g. `hud serve chat_env.py` → `HUD_ENV_URL=tcp://127.0.0.1:8765`) instead of spawning.
+You configure the server through environment variables:
+
+| Variable | What it controls |
+|----------|------------------|
+| `HUD_MODEL` | The agent's model, routed through the gateway (needs `HUD_API_KEY`). |
+| `HUD_TASK` / `HUD_ENV` | Which task row to serve. |
+| `HUD_SOURCE` | Spawns a different env source. |
+| `HUD_ENV_URL` | Attaches each turn to an already-served control channel instead of spawning. For example, `hud serve chat_env.py` then `HUD_ENV_URL=tcp://127.0.0.1:8765`. |
 
 ## See also
 
diff --git a/docs/v6/cookbooks/coding-agent.mdx b/docs/v6/cookbooks/coding-agent.mdx
index 5fb1c29c..17c9f0c9 100644
--- a/docs/v6/cookbooks/coding-agent.mdx
+++ b/docs/v6/cookbooks/coding-agent.mdx
@@ -4,13 +4,13 @@ description: "Run a coding agent inside a HUD shell-and-files environment, with
 icon: "code"
 ---
 
-A complete, runnable example: an environment with a managed shell, a task that asks the agent to make a failing test pass, and a `BashGrader` that scores by running the test suite.
+A coding task gives the agent a shell and some files, asks for a change, and grades the result by running it. This example does exactly that: an environment with a sandboxed shell, a task that asks the agent to make a failing test pass, and a `BashGrader` that scores by running the test suite.
 
 ## The environment
 
-The workspace gives the agent a sandboxed shell and files - the env starts it and publishes the `shell` capability when it serves. We seed a buggy module and a test in `@env.initialize`, then declare the task - the grader runs `pytest` and scores by exit code.
+The agent works in a **workspace**: a sandboxed shell and file system it reaches over the `ssh` capability, which the env publishes when it serves. In `@env.initialize` we seed a buggy module and a test, then declare the task. Its grader runs `pytest` and scores by exit code.
 
-One design point matters here: **the grader runs an authoritative copy of the test that lives outside the agent's workspace.** The agent gets its own copy to read and run, but if the grader re-ran that editable copy, the cheapest path to a passing `pytest` would be weakening or deleting the test - classic reward hacking.
+The grader runs an **authoritative copy of the test that lives outside the agent's workspace**. The agent gets its own copy to read and run, but if the grader re-ran that editable copy, the cheapest path to a passing `pytest` would be to weaken or delete the test - classic reward hacking. Keeping the scoring copy out of reach closes that path.
 
 ```python env.py
 from pathlib import Path
diff --git a/docs/v6/cookbooks/index.mdx b/docs/v6/cookbooks/index.mdx
index 538d8dd7..b197ac55 100644
--- a/docs/v6/cookbooks/index.mdx
+++ b/docs/v6/cookbooks/index.mdx
@@ -4,11 +4,12 @@ description: "Complete, runnable cookbook examples you can copy and adapt: codin
 icon: "book-open"
 ---
 
-Cookbooks are complete, runnable examples — each one is a small project you can
-copy and adapt. They all live in the
+Cookbooks are complete, runnable projects you can copy and adapt. Each one shows
+an environment, an agent, and a grader working end to end, so you can see a whole
+evaluation rather than one concept at a time. They all live in the
 [`cookbooks/`](https://github.com/hud-evals/hud-python/tree/main/cookbooks)
-directory of the SDK repo. The ones below with a walkthrough have a full guide
-here; the rest are best read straight from the source.
+directory of the SDK repo. The examples below with a **walkthrough** have a full
+guide on this site; the rest are best read straight from their source.
 
 ## Walkthroughs
 
@@ -31,13 +32,13 @@ here; the rest are best read straight from the source.
 
 ## More runnable examples
 
-These ship in the repo without a separate walkthrough — read the README in each
+These ship in the repo without a separate walkthrough. Read the README in each
 directory to run them.
 
 <CardGroup cols={2}>
   <Card title="RL training" icon="dumbbell" href="https://github.com/hud-evals/hud-python/tree/main/cookbooks/rl-training">
     On-policy RL: roll out a taskset with the current weights, train on the
-    resulting trajectories, and serve the updated weights for the next rollout —
+    resulting trajectories, and serve the updated weights for the next rollout,
     all under one trainable model string.
   </Card>
   <Card title="Connect Four self-play" icon="table-cells" href="https://github.com/hud-evals/hud-python/tree/main/cookbooks/connect4-selfplay">
diff --git a/docs/v6/cookbooks/ops-diagnostics.mdx b/docs/v6/cookbooks/ops-diagnostics.mdx
index 6236b454..9f719bb1 100644
--- a/docs/v6/cookbooks/ops-diagnostics.mdx
+++ b/docs/v6/cookbooks/ops-diagnostics.mdx
@@ -4,11 +4,11 @@ description: "Walk through an ops diagnostics task where the agent gathers logs,
 icon: "stethoscope"
 ---
 
-A complete, runnable example of an **investigation** task: the agent reads several artifacts, integrates the evidence, and produces a root-cause diagnosis graded by an LLM judge. This is the shape of a good training task - multi-step, multi-channel, and graded on substance.
+An **investigation** task asks the agent to reach a conclusion that no single piece of evidence gives away. Here the agent reads several log files, integrates what they say, and produces a root-cause diagnosis that an LLM judge grades against a rubric. This is the shape of a good training task - multi-step, multi-channel, and graded on substance rather than keywords.
 
 ## The environment
 
-We give the agent shell access to a directory of logs and traces, then ask for a diagnosis. The agent must read across files - no single artifact contains the answer.
+We give the agent shell access to a directory of logs and traces, then ask for a diagnosis. The cause sits in one file and the symptoms in others, so the agent has to read across them - no single artifact contains the answer.
 
 ```python env.py
 from pathlib import Path
diff --git a/docs/v6/cookbooks/robot-benchmark.mdx b/docs/v6/cookbooks/robot-benchmark.mdx
index 9760bb3b..f9e6521e 100644
--- a/docs/v6/cookbooks/robot-benchmark.mdx
+++ b/docs/v6/cookbooks/robot-benchmark.mdx
@@ -9,11 +9,11 @@ tag: "Beta"
 The `robot` capability is in **beta** - see the [Robots reference](/v6/advanced/robots).
 </Note>
 
-This cookbook runs **pi0.5** against **LIBERO** (a Franka Panda manipulation benchmark) packaged as a Docker image: three episodes, each in a fresh container, graded by the sim's own success check. The policy runs in *your* process on your GPU; the container is CPU-only and publishes exactly one port.
+This cookbook runs **pi0.5** against **LIBERO** (a Franka Panda manipulation benchmark) packaged as a Docker image: three episodes, each in a fresh container, graded by the sim's own success check. The split of work is the thing to notice - the policy runs in *your* process on your GPU, while the container is CPU-only and publishes exactly one port.
 
 ## The environment
 
-The env module is declare-only - a sim **bridge**, an **endpoint**, and two-yield templates (this is `demos/inventory/envs/libero/env.py`, abbreviated):
+The env module only declares; it runs no policy of its own. It wires three things together: a **bridge** that drives the simulator, a **`RobotEndpoint`** that exposes the bridge as a capability, and two-yield task templates. This is `demos/inventory/envs/libero/env.py`, abbreviated:
 
 ```python env.py
 from hud import Environment
@@ -100,7 +100,11 @@ asyncio.run(main())
 python run_libero.py
 ```
 
-`DockerRuntime` is the placement: each rollout `docker run`s a fresh container, publishes the control port, connects, and removes the container afterward. The agent reads the env's **contract** from the manifest at connect time and wires cameras/state/actions itself - there is no shared config between this script and the image. The robot WebSocket binds container-loopback and rides the control port via capability tunneling.
+Here `DockerRuntime` sets the placement, and each rollout is self-contained:
+
+- **The container** is created fresh with `docker run`, publishes its control port, is connected to, and is removed when the episode ends.
+- **The agent** reads the env's **contract** from the manifest at connect time and wires cameras, state, and actions itself - there is no shared config between this script and the image.
+- **The robot WebSocket** binds to container-loopback and rides that single control port through capability tunneling.
 
 For heavy sims (or sweeps), skip the per-episode boot with one long-lived container:
 

From 45fdfe3e03fd21144bf521b05b5c9a89d1fa85e6 Mon Sep 17 00:00:00 2001
From: lukass16 <lukasskellijs@gmail.com>
Date: Wed, 24 Jun 2026 21:18:15 -0700
Subject: [PATCH 12/16] docs(v6): rewrite reference pages and drop filetracking
 capability

Rework the v6 reference set (agents, capabilities, environment, graders,
runtime, tasks, training, types) into a tighter, signature-first style, and fix
the extending cross-link to the new environment anchors.

Align the capabilities and environment pages with main's "enable workspace file
tracking by default" change: remove filetracking as a public capability and drop
the FileTrackingClient, and document file tracking as workspace-owned telemetry
that runs by default (opt out with track_files=False or
HUD_FILE_TRACKING_ENABLED=false).

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/v6/advanced/extending.mdx     |   2 +-
 docs/v6/reference/agents.mdx       |  95 ++++++------
 docs/v6/reference/capabilities.mdx | 197 ++++++++++++++-----------
 docs/v6/reference/environment.mdx  | 228 ++++++-----------------------
 docs/v6/reference/graders.mdx      |  32 +++-
 docs/v6/reference/runtime.mdx      |  78 ++++------
 docs/v6/reference/tasks.mdx        | 217 ++++++++-------------------
 docs/v6/reference/training.mdx     | 196 ++++++++-----------------
 docs/v6/reference/types.mdx        |  36 ++++-
 9 files changed, 419 insertions(+), 662 deletions(-)

diff --git a/docs/v6/advanced/extending.mdx b/docs/v6/advanced/extending.mdx
index 02ec4c80..0bdf59d9 100644
--- a/docs/v6/advanced/extending.mdx
+++ b/docs/v6/advanced/extending.mdx
@@ -281,7 +281,7 @@ env = Environment(
 Run the FastMCP server alongside the environment so the URL is live - for local iteration,
 `tools.run(transport="http", host="127.0.0.1", port=8080)`; in a built image, start it from your
 container entrypoint or an
-[`@env.initialize`](/v6/reference/environment#lifecycle-hooks-set-up-and-tear-down) hook.
+[`@env.initialize`](/v6/reference/environment#methods) hook.
 
 ### How it looks to the orchestrator
 
diff --git a/docs/v6/reference/agents.mdx b/docs/v6/reference/agents.mdx
index 3dd4fcb5..7a8994fa 100644
--- a/docs/v6/reference/agents.mdx
+++ b/docs/v6/reference/agents.mdx
@@ -31,15 +31,15 @@ from hud.agents import create_agent
 agent = create_agent("claude-sonnet-4-5")   # routed through the gateway
 ```
 
-The HUD gateway is an OpenAI-compatible endpoint (`inference.hud.ai`) that fronts every provider behind
-your single `HUD_API_KEY`, so you switch between Claude, GPT, Gemini, or Grok <u>by name alone</u>, with
-unified tracing. `create_agent` accepts any id the gateway knows (`claude-...`, `gpt-...`, `gemini-...`,
-`grok-...`); extra kwargs pass through to the agent's config.
+The HUD gateway is an OpenAI-compatible endpoint (`settings.hud_gateway_url`, default
+`https://inference.beta.hud.ai`) that fronts every provider behind your single `HUD_API_KEY`, so you
+switch between Claude, GPT, and Gemini by name alone, with unified tracing. `create_agent` accepts any id
+the gateway knows (`claude-...`, `gpt-...`, `gemini-...`); extra kwargs pass through to the agent's
+config.
 
-The reason this is one line: built-in agents are **catalog-driven**. Each run they read the
-environment's manifest, open the capabilities they support, build the matching provider tools, and loop
-against `run.prompt_messages`. <u>Declaring a capability on the environment is enough; you never wire
-tools.</u>
+Built-in agents are **catalog-driven**: each run they read the environment's manifest, open the
+capabilities they support, build the matching provider tools, and loop against `run.prompt_messages`.
+Declaring a capability on the environment is enough; you never wire tools.
 
 ### Provider agents
 
@@ -66,45 +66,55 @@ points at any compatible server (vLLM, a local model) via `base_url`; `ClaudeSDK
 CLI over an `ssh` capability, against the env's filesystem. Every knob (`model`, `max_steps`,
 `system_prompt`, `citations_enabled`) lives on the config; `__call__(run)` takes only the run.
 
-## Running an agent
+## create_agent {#create-agent}
+
+```python
+create_agent(model: str, **kwargs) -> GatewayAgent
+```
+
+The `create_agent` function resolves `model` to a gateway agent type and returns that provider agent
+wired to the gateway. Extra `kwargs` forward to the matched provider config (the `*Config` for the
+resolved type), with `model` and a gateway `model_client` filled in. Passing `completion_kwargs` only
+works when `model` resolves to `OpenAIChatAgent`, since `completion_kwargs` lives only on
+`OpenAIChatConfig`.
 
-Run a task with an agent two ways.
+A model id maps to one of four gateway agent types (`AgentType`), each a provider agent:
 
-**Programmatically** - pass the agent to `task.run` / `taskset.run` with a [runtime](/v6/reference/runtime):
+| `AgentType` | Agent class |
+|-------------|-------------|
+| `claude` | `ClaudeAgent` |
+| `openai` | `OpenAIAgent` |
+| `gemini` | `GeminiAgent` |
+| `openai_compatible` | `OpenAIChatAgent` |
+
+For a provider key instead of the gateway, or for `ClaudeSDKAgent` (not a gateway type), construct the
+provider agent directly.
+
+## Agent
+
+Every agent implements the `Agent` base class (`hud.agents.base`): one abstract method,
+`__call__(run: Run) -> None`. An agent drives the live [`Run`](/v6/reference/types#run) to completion,
+filling `run.trace` in place; the graded answer is `run.trace.content`. An agent is stateless per run -
+everything comes from `run` - so one instance drives many concurrent rollouts.
+
+## Running an agent
+
+Run a task with an agent two ways. **Programmatically**, pass the agent to `Task.run` or `Taskset.run`
+with a [runtime](/v6/reference/runtime):
 
 ```python
 from hud.agents import create_agent
-from hud.eval import LocalRuntime
-from tasks import TASKS
+from hud.eval import LocalRuntime, Taskset
 
 agent = create_agent("claude-sonnet-4-5")
-job = await TASKS.run(agent, runtime=LocalRuntime("env.py"))
+taskset = Taskset.from_file("tasks.py")        # scaffolded tasks.py exports a list of tasks
+job = await taskset.run(agent, runtime=LocalRuntime("env.py"))
 print(job.reward)
 ```
 
-**From the [CLI](/v6/reference/cli#hud-eval)** - `hud eval` takes a task source (`.py`, a directory, or
-`.json`/`.jsonl`) and an agent name (`claude`, `openai`, `gemini`, `openai_compatible`), runs each
-rollout in a fresh env subprocess, grades it, and prints the reward:
-
-```bash
-hud eval tasks.py claude                       # first task, one rollout
-hud eval tasks.py openai -m gpt-5 --group 3    # a pinned model, 3 rollouts each
-hud eval tasks.py claude --all                 # every task in the source
-```
-
-Flags override the agent's config for that run:
-
-| Flag | Effect |
-|------|--------|
-| `--model`, `-m` | Pin a specific model id. |
-| `--group N` | Run each task N times, to see the reward spread. |
-| `--max-steps N` | Cap agent steps per task. |
-| `--all` / `--full` | Run the whole source (`--full` also auto-responds, 100 steps). |
-| `--gateway` | Force calls through the gateway even when a provider key is set. |
-
-With only a `HUD_API_KEY` set, calls route through the gateway; with a provider key present they go
-straight to the provider. See the [CLI reference](/v6/reference/cli#hud-eval) for the full flag set and key
-resolution.
+**From the CLI**, `hud eval` takes a task source and an agent name (`claude`, `openai`, `gemini`,
+`openai_compatible`); see [running an eval](/v6/guides/running-an-eval) for the walkthrough and the
+[CLI reference](/v6/reference/cli#hud-eval) for the full flag set.
 
 ## Bring your own harness
 
@@ -113,11 +123,6 @@ the final answer to `run.trace.content` (what gets graded). Since this is outsid
 the seam, the `Run` object you work with, the step types you record, and worked examples live in
 [Extending HUD](/v6/advanced/extending#bring-your-own-harness).
 
-## See also
-
-<CardGroup cols={2}>
-<Card title="Bring your own harness" icon="screwdriver-wrench" href="/v6/advanced/extending#bring-your-own-harness" />
-<Card title="Capabilities" icon="plug" href="/v6/reference/capabilities" />
-<Card title="Types: Run & Trace" icon="code" href="/v6/reference/types" />
-<Card title="Robots (beta)" icon="robot" href="/v6/advanced/robots" />
-</CardGroup>
+To run an agent end to end see [running an eval](/v6/guides/running-an-eval); for where each rollout runs
+see [runtimes](/v6/reference/runtime), and for the [`Run`](/v6/reference/types#run) an agent fills see
+[types](/v6/reference/types).
diff --git a/docs/v6/reference/capabilities.mdx b/docs/v6/reference/capabilities.mdx
index c57a6809..808344e7 100644
--- a/docs/v6/reference/capabilities.mdx
+++ b/docs/v6/reference/capabilities.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Capabilities"
-description: "Capabilities are the connections an environment exposes to agents: how to declare each one, spin it up at runtime, and attach the matching client."
+description: "The wire protocols an environment exposes, each protocol's factory signature, and the clients that attach to them."
 icon: "plug"
 ---
 
@@ -29,66 +29,52 @@ A capability is `(name, protocol, url, params)` - concrete wire data carrying th
 | `url` | `str` | Connection URL. |
 | `params` | `dict` | Protocol-specific connection params. |
 
-Each protocol has a **factory** (`Capability.ssh`, `.mcp`, `.cdp`, `.rfb`, `.robot`) - a classmethod that builds a valid `Capability` for that protocol, so you don't need to fill in the `name`, `protocol`, `url`, and `params` fields by hand. It normalizes the URL (fills in the default scheme and port), sets the right `protocol` id, and packs the protocol-specific params (e.g. `host_pubkey` for `ssh`, `display` for `rfb`). `cap.to_manifest()` / `Capability.from_manifest(data)` round-trip it on the wire.
+Each protocol has a **factory** (`Capability.ssh`, `.mcp`, `.cdp`, `.rfb`, `.robot`) - a classmethod that builds a valid `Capability` for that protocol, so you don't fill in the four fields by hand. It normalizes the URL (fills in the default scheme and port), sets the right `protocol` id, and packs the protocol-specific params. `cap.to_manifest()` / `Capability.from_manifest(data)` round-trip it on the wire.
 
 ## Spinning up a capability
 
-Every capability points at a daemon. If the daemon already exists (a managed service, a remote box), just describe it with its factory and you're done. The case worth a closer look is **a daemon the environment runs itself** - an MCP server, a browser, a VNC display. The flow is the same four steps every time:
+Every capability points at a daemon. A daemon that already exists (a managed service, a remote box) is described with its factory and you're done. A daemon the **environment runs itself** follows the same four steps inside an `@env.initialize` hook:
 
-```python env.py
-@env.initialize
-async def _up():
-    start_daemon(host="127.0.0.1", port=PORT)            # 1. launch it (subprocess / task)
-    await wait_until_listening("127.0.0.1", PORT)         # 2. block until it accepts connections
-    env.add_capability(Capability.mcp(name="tools",      # 3. publish its address
-                                      url=f"http://127.0.0.1:{PORT}/mcp"))
-
-@env.shutdown
-async def _down():
-    stop_daemon()                                        # 4. tear it down with the env
-```
+1. **Launch it** as a subprocess or background task, bound to `127.0.0.1`.
+2. **Block until it is listening** before publishing. A subprocess returns before its port is bound, so poll the port (or `asyncio.sleep` for a daemon you know starts fast). The environment runs every `@env.initialize` hook to completion before accepting a client, so a capability published here is live the moment any agent connects.
+3. **Publish its address** with [`env.add_capability(...)`](/v6/reference/environment#methods).
+4. **Tear it down** in `@env.shutdown`.
 
-**Wait until it's actually listening (step 2).** Launching a subprocess or background task returns *before* the daemon has bound its port - publish the capability now and an agent can connect before anything is there to answer. The environment runs *every* `@env.initialize` hook to completion before it accepts a single client, so blocking here is what guarantees the capability is live the moment any agent connects. The robust way is to poll the port in a loop until it answers (as the example envs do); a brief `asyncio.sleep` is fine for a daemon you know starts fast.
+Bind every daemon to `127.0.0.1`: the environment exposes a single control port, and the HUD client transparently forwards a `127.0.0.1` capability through that port to the daemon inside. A capability already on a public address is used as-is.
 
-**Bind to `127.0.0.1` (step 1 and 3).** Bind every daemon to `127.0.0.1` so it's only reachable from inside the environment - that's exactly what you want, because <u>the environment exposes a single control port and nothing else</u>. The HUD client transparently forwards a `127.0.0.1` capability through that one control port to the daemon inside; a capability that's already on a public address is used as-is. So you bind, publish, and never think about networking - <u>one port in, every capability reachable</u>.
+## Factories
 
 ### `ssh` - a sandboxed shell
 
-The shell case is built in via [`Workspace`](#workspace) - a built-in daemon that manages a `bwrap`-isolated directory and serves it over `ssh`. `env.workspace(root)` starts it, publishes its `ssh` capability, and stops it with the env - one line, no hook:
-
-```python env.py
-from hud.environment import Environment
-
-env = Environment(name="coder")
-env.workspace("workspace")   # publishes "shell" (ssh/2) when the env serves
+```text
+Capability.ssh(*, name="shell", url, user="agent", host_pubkey, client_key=None, client_key_path=None, shell=None)
 ```
 
-<Note>
-Use a relative path (`"workspace"`, created next to `env.py`). Sandbox isolation (`bwrap`) is Linux-only - unisolated elsewhere, isolated in a built image.
-</Note>
-
-To run a workspace yourself, drive its lifecycle and publish `ws.capability()` by hand:
-
-```python env.py
-from hud.environment import Environment, Workspace
+The shell case is built in via [`Workspace`](#workspace), so you rarely call this factory directly. [`env.workspace(root)`](/v6/reference/environment#methods) starts a workspace, publishes its `ssh` capability, and stops it with the env.
 
-env = Environment(name="coder")
-ws = Workspace("workspace", host="127.0.0.1", port=0)   # port 0 → ephemeral
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `str` | Capability name. Default `"shell"`. |
+| `url` | `str` | SSH URL (`host[:port]`, default port `22`). |
+| `user` | `str` | SSH username. Default `"agent"`. |
+| `host_pubkey` | `str` | Server host public key (for the harness's `known_hosts`). |
+| `client_key` | `str \| None` | Private key *content*; authenticates across a container boundary. |
+| `client_key_path` | `str \| None` | Path to a key file; only works when client and daemon share a filesystem. |
+| `shell` | `str \| None` | Remote shell type (`bash` / `powershell` / `cmd`); auto-detected from `sys.platform`. |
 
-@env.initialize
-async def _up():
-    await ws.start()                          # binds, generates keys; idempotent
-    env.add_capability(ws.capability("shell"))
+### `mcp` - your own tools
 
-@env.shutdown
-async def _down():
-    await ws.stop()
+```text
+Capability.mcp(*, name="tools", url, auth_token=None)
 ```
 
-### `mcp` - your own tools
-
-Serve bespoke tools on a [FastMCP](https://gofastmcp.com) server. The streamable-HTTP transport serves under `/mcp`, so that path is part of the published URL:
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `str` | Capability name. Default `"tools"`. |
+| `url` | `str` | `ws` / `wss` / `http` / `https` URL (no stdio). The streamable-HTTP transport serves under `/mcp`. |
+| `auth_token` | `str \| None` | Optional bearer token. |
 
+<Accordion title="Example env.py">
 ```python env.py
 import asyncio
 
@@ -110,11 +96,11 @@ _task: asyncio.Task | None = None
 @env.initialize
 async def _up():
     global _task
-    if _task is None:                          # idempotent
+    if _task is None:
         _task = asyncio.create_task(
             server.run_async(transport="http", host="127.0.0.1", port=8040)
         )
-        await asyncio.sleep(1.0)               # wait until the server is ready
+        await asyncio.sleep(1.0)
     env.add_capability(Capability.mcp(name="tools", url="http://127.0.0.1:8040/mcp"))
 
 @env.shutdown
@@ -124,13 +110,23 @@ async def _down():
         _task.cancel()
         _task = None
 ```
-
-`Capability.mcp` accepts `ws`/`wss`/`http`/`https` URLs (no stdio) and an optional `auth_token=`.
+</Accordion>
 
 ### `cdp` - a browser
 
-Launch Chromium with a DevTools port. Playwright ships the binary (`playwright install chromium`); run it as a subprocess so the CDP endpoint is reachable at `http://127.0.0.1:9222`:
+```text
+Capability.cdp(*, name="browser", url, target_id=None)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `str` | Capability name. Default `"browser"`. |
+| `url` | `str` | DevTools URL (default scheme `ws`, default port `9222`). |
+| `target_id` | `str \| None` | Optional CDP target id. |
 
+Playwright ships the Chromium binary (`playwright install chromium`). Add `--no-sandbox` to the launch flags only when running as root in a container.
+
+<Accordion title="Example env.py">
 ```python env.py
 import asyncio
 import tempfile
@@ -156,7 +152,7 @@ async def _up():
             "--no-first-run",
             "--user-data-dir=" + tempfile.mkdtemp(prefix="cdp_"),
         )
-        await asyncio.sleep(1.0)               # wait until Chromium is ready
+        await asyncio.sleep(1.0)
     env.add_capability(Capability.cdp(name="browser", url="http://127.0.0.1:9222"))
 
 @env.shutdown
@@ -167,13 +163,24 @@ async def _down():
         await _proc.wait()
         _proc = None
 ```
-
-`Capability.cdp` defaults to port `9222` and takes an optional `target_id=`. (Add `--no-sandbox` only when running as root in a container.)
+</Accordion>
 
 ### `rfb` - a virtual screen
 
-Full computer-use is a VNC server over a virtual display. On Linux, `Xvfb` paints the framebuffer and `x11vnc` serves it (`apt install xvfb x11vnc`):
+```text
+Capability.rfb(*, name="screen", url, password=None, display=0)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `str` | Capability name. Default `"screen"`. |
+| `url` | `str` | VNC URL (default scheme `rfb`). When the URL omits a port it defaults to `5900 + display`. |
+| `password` | `str \| None` | Optional VNC password. |
+| `display` | `int` | VNC display number. Default `0`. Host multiple screens by publishing one `rfb` capability per display. |
+
+On Linux, `Xvfb` paints the framebuffer and `x11vnc` serves it (`apt install xvfb x11vnc`).
 
+<Accordion title="Example env.py">
 ```python env.py
 import asyncio
 
@@ -190,12 +197,12 @@ async def _up():
         xvfb = await asyncio.create_subprocess_exec(
             "Xvfb", ":0", "-screen", "0", "1280x1024x24",
         )
-        await asyncio.sleep(0.5)               # let the X server come up first
+        await asyncio.sleep(0.5)
         vnc = await asyncio.create_subprocess_exec(
             "x11vnc", "-display", ":0", "-rfbport", "5900",
             "-localhost", "-forever", "-nopw",
         )
-        await asyncio.sleep(1.0)               # wait until VNC is ready
+        await asyncio.sleep(1.0)
         _procs = (xvfb, vnc)
     env.add_capability(Capability.rfb(name="screen", url="rfb://127.0.0.1", display=0))
 
@@ -208,8 +215,7 @@ async def _down():
             await p.wait()
         _procs = None
 ```
-
-`Capability.rfb` listens on `5900 + display` and takes an optional `password=`. Host multiple screens by publishing one `rfb` capability per `display`.
+</Accordion>
 
 ### `robot` - an observation/action loop
 
@@ -217,9 +223,13 @@ async def _down():
 Capability.robot(*, name="robot", url, contract)
 ```
 
-The robot control loop *(beta)*, carried over the `openpi/0` wire protocol. It's an **openpi-like** protocol: it reuses openpi's wire format (msgpack with recursive numpy serialization) and its flat observation/action naming (`observation/...` keys, `actions`), so an openpi policy server and a HUD env speak the same bytes. The one fundamental difference is **role assignment** - in openpi a policy *server* answers inference requests, but here the **environment is the server** (it owns the world and pushes observations) and the **agent is the client** (it acts, replying with actions).
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `str` | Capability name. Default `"robot"`. |
+| `url` | `str` | WebSocket URL (default scheme `ws`, default port `9091`). |
+| `contract` | `dict` | The env's self-describing schema: `robot_type`, `control_rate`, and a `features` map (each feature's `role`, layout, and normalization `stats`). |
 
-The `contract` is the environment's full self-describing schema - `robot_type`, `control_rate`, and every observation/action feature - carried in the manifest so the agent wires itself with no shared config. The environment drives its simulator through a [`RobotEndpoint`](/v6/advanced/robots) (not the bridge directly, although possible), and the endpoint builds the capability for you once started:
+The robot control loop *(beta)* runs over the `openpi/0` protocol. It is **openpi-like**: it reuses openpi's msgpack-numpy wire format and flat observation/action naming, but the **environment is the server** (it owns the world and pushes observations) and the **agent is the client** (it acts, replying with actions). The environment drives its simulator through a [`RobotEndpoint`](/v6/advanced/robots), which builds the capability once started:
 
 ```python
 endpoint = RobotEndpoint(MySimBridge())   # drive the sim only through the endpoint
@@ -232,12 +242,9 @@ async def _up():
 
 See [Robots](/v6/advanced/robots) for the bridge, the endpoint, the harness, and the contract spec.
 
-### Workspace file tracking
+## Workspace file tracking
 
-Workspace file tracking records what changed in a [`Workspace`](#workspace) over a run, so HUD can
-show file diffs in the trace. It runs with the workspace lifecycle and is not a tool the agent calls.
-`env.workspace(...)` enables it by default with conservative tracking limits and secret redaction; set
-`HUD_FILE_TRACKING_ENABLED=false` or pass `track_files=False` to opt out:
+Workspace file tracking records what changed in a [`Workspace`](#workspace) over a run, so HUD can show file diffs in the trace. It runs with the workspace lifecycle and is not a tool the agent calls. `env.workspace(...)` enables it by default (the `HUD_FILE_TRACKING_ENABLED` setting); set `HUD_FILE_TRACKING_ENABLED=false` or pass `track_files=False` to opt out:
 
 ```python env.py
 env.workspace("workspace")                     # ssh plus file tracking
@@ -260,42 +267,56 @@ The bundled provider agents open these automatically based on which capabilities
 
 ## Workspace
 
-A `Workspace` is not itself a capability - it's the built-in workspace daemon. It serves `ssh` for
-agent access and, when enabled, `filetracking` for rollout telemetry. For `mcp`, `cdp`, and `rfb` you
-stand up the daemon yourself (above), but for a shell you just attach a workspace.
+A `Workspace` is not itself a capability - it's the built-in workspace daemon. It serves `ssh` for agent access and, when enabled, file tracking for rollout telemetry. For `mcp`, `cdp`, and `rfb` you stand up the daemon yourself.
 
-Concretely it's a directory plus a `bwrap`-isolated SSH server (bash + chroot'd SFTP).
-`env.workspace(root, ...)` wires its whole lifecycle: the environment brings it up (keys, socket,
-accept loop, and file tracking by default) when it serves and tears it down on `env.stop()`.
-Extra kwargs configure the sandbox - mounts, network, env vars, guest path, fixed ports, your own
-keys:
+Concretely it's a directory plus a `bwrap`-isolated SSH server (bash + chroot'd SFTP). [`env.workspace(root, ...)`](/v6/reference/environment#methods) wires its whole lifecycle; construction is pure data, with keys, sockets, and the root directory materializing only at serve time. To run one outside an env, drive its lifecycle directly and publish `ws.capability()`:
 
 ```python
-from hud.environment import Environment, Mount
+from hud.environment import Environment, Workspace
 
 env = Environment(name="coder")
-env.workspace(
-    "/workspace",
-    network=True,
-    mounts=[Mount("ro", src="/data", dst="/data")],
-)
+ws = Workspace("workspace", host="127.0.0.1", port=0)   # port 0 = ephemeral
+
+@env.initialize
+async def _up():
+    await ws.start()                          # binds, generates keys; idempotent
+    env.add_capability(ws.capability("shell"))
+
+@env.shutdown
+async def _down():
+    await ws.stop()
 ```
 
-To run one outside an env, drive its lifecycle directly and publish `ws.capability()` as a concrete `ssh` capability:
+<Note>
+Use a relative path (`"workspace"`, created next to `env.py`). Sandbox isolation (`bwrap`) is Linux-only - unisolated elsewhere, isolated in a built image.
+</Note>
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `root` | `Path \| str` | Directory served (created at start). |
+| `mounts` | `Sequence[Mount]` | Extra bwrap mounts. Default `()`. |
+| `network` | `bool` | Allow network inside the sandbox. Default `False`. |
+| `env` | `Mapping[str, str] \| None` | Environment variables for the sandbox. |
+| `system_mounts` | `Sequence[Mount] \| None` | Override the default system mounts. |
+| `guest_path` | `str` | Path the root mounts at inside the sandbox. Default `"/workspace"`. |
+| `host` | `str` | SSH bind host. Default `"127.0.0.1"`. |
+| `port` | `int` | SSH bind port (`0` binds an ephemeral port). Default `0`. |
+| `user` | `str` | SSH username. Default `"agent"`. |
+| `host_key_path` | `Path \| None` | Reuse a host key instead of generating one. |
+| `authorized_client_keys` | `list[Path] \| None` | Authorize specific client public keys. |
+| `track_files` | `bool` | Serve file-tracking telemetry over the workspace lifecycle. Constructor default `False`; `env.workspace(...)` defaults it to `HUD_FILE_TRACKING_ENABLED` (on). |
 
 | Member | Description |
 |--------|-------------|
-| `Workspace(root, *, host="127.0.0.1", port=0, mounts=(), network=False, env=None, user="agent", ...)` | Construct. `port=0` binds an ephemeral port. |
 | `await ws.start()` | Start the SSH accept loop (idempotent). |
-| `ws.capability(name="shell")` | The resolved `ssh` `Capability` (materializes keys, binds the socket). |
 | `await ws.stop()` | Stop accepting sessions and release the socket. |
-| `ws.ssh_url` / `ws.ssh_host_pubkey` | Connection address and host key. |
+| `ws.capability(name="shell")` | The resolved `ssh` `Capability` (materializes keys, binds the socket). |
+| `ws.file_tracking_capability(name="filetracking")` | The `filetracking/1` `Capability` (requires `track_files=True`). |
+| `ws.tracks_files` | Whether this workspace serves a `filetracking/1` capability. |
+| `ws.ssh_url` / `ws.ssh_host_pubkey` / `ws.ssh_client_key_path` / `ws.ssh_user` | Connection address, host key, client key path, and username. |
 | `ws.bwrap_available` | Whether `bwrap` isolation is active. |
+| `ws.bwrap_argv(...)` / `ws.shell_argv(...)` | Build argv for your own subprocess (bwrap'd / per-session shell). |
 
-## See also
+A `Mount` (`hud.environment`) configures a single bwrap mount, `Mount(kind, src, dst, optional)`, where `kind` is one of `ro`, `rw`, `tmpfs`, `symlink`, `proc`, `dev`.
 
-<CardGroup cols={2}>
-<Card title="Environment" icon="cube" href="/v6/reference/environment" />
-<Card title="Agents" icon="robot" href="/v6/reference/agents" />
-<Card title="Tasks & Tasksets" icon="list-check" href="/v6/reference/tasks" />
-</CardGroup>
+For authoring a complete environment around a capability, see [creating an environment](/v6/guides/creating-an-environment); for the object and serving API, see [environment](/v6/reference/environment).
diff --git a/docs/v6/reference/environment.mdx b/docs/v6/reference/environment.mdx
index 932841f1..45f35e89 100644
--- a/docs/v6/reference/environment.mdx
+++ b/docs/v6/reference/environment.mdx
@@ -1,133 +1,48 @@
 ---
 title: "Environments"
-description: "Declare a HUD environment in a single env.py file: container contents, templates, capabilities, and how the environment is built and served."
+description: "The Environment control object, its registration methods, and how to serve one over the wire protocol."
 icon: "cube"
 ---
 
-An **environment** is the world your agent acts in - a shell, a browser, a desktop, a robot
-simulator. In HUD the word covers two things, and keeping them apart makes everything else clearer:
+An **environment** is the world an agent acts in - a shell, a browser, a desktop, a robot simulator.
+The `Environment` object is the wire-protocol control handle for one: it holds the capabilities and
+tasks registered against it and answers an agent harness over the [protocol](/v6/advanced/protocol).
+Authoring an `env.py` lives in [creating an environment](/v6/guides/creating-an-environment); this
+page is the object and its serving API.
 
-- the **`Environment` object** - a lightweight control handle. It doesn't hold the world itself;
-  it's where you *register* what the environment exposes.
-- the **`env.py` file** - the whole environment you author, serve, and ship: the object plus
-  everything registered on it.
-
-The object is the handle, the file is the environment. You build one by constructing the object and
-registering three kinds of things against it: the access the agent gets (**capabilities**), optional
-setup and teardown (**lifecycle hooks**), and the work to be done (**tasks**). The rest of this page
-walks through declaring each, then the object and serving details underneath.
-
-## Declaring an environment
-
-Everything lives in one file, conventionally `env.py`: an ordinary Python module that constructs the
-`Environment` and registers its capabilities, hooks, and tasks against it. A complete one is small -
-declare the object, give it the access the agent needs, optionally set up and tear down state, and
-define at least one task:
-
-```python env.py
-from hud import Environment
-from hud.capabilities import Capability
-from hud.graders import LLMJudgeGrader
-
-env = Environment(name="my-env", capabilities=[          # the object + the access it exposes
-    Capability.ssh(name="shell", url="<url>", host_pubkey="<key>"),
-])
-
-@env.initialize                                          # optional: set up state before serving
-async def _up():
-    ...
-
-@env.template()                                          # one or more tasks: a prompt and a reward
-async def my_task(...):
-    answer = yield "<prompt>"
-    result = await LLMJudgeGrader.grade(answer=answer, criteria=[...])
-    yield result.value
-```
-
-When you serve, HUD imports the module, finds the `Environment` object in it, and runs everything
-registered on it. The only contract is "this module defines an `Environment`", which is what makes
-the declaration portable: the same `env.py` runs locally, in a container, or on HUD with nothing
-changed but the [runtime](/v6/reference/runtime).
-
-### Capabilities: the access you expose
-
-A **capability** is the agent's way in - a connection the system already speaks. A machine has a
-shell, so it speaks `ssh`; a web app has a browser, so it speaks `cdp`. You expose the connection the
-system already has, and the agent drives it natively with its own tools. Two things fall out for
-free: <u>wrapping any system is trivial</u>, and <u>nothing about the agent is baked in</u> - the
-same environment keeps working with any model or harness, today's or next year's.
+## The `Environment` object
 
-The most common capability is a shell: a **`Workspace`** is a sandboxed directory the agent works in
-over `ssh`, and `env.workspace(root)` brings it up, publishes its `ssh` capability, starts file
-tracking by default, and tears it down with the env - one line, no hook:
+`hud.environment.Environment` is the lightweight control object the whole file hangs off. When
+served, it acts as the *server* an agent harness connects to: it answers `hello` with its
+capabilities and runs its tasks on request.
 
-```python env.py
+```python
 from hud import Environment
 
-env = Environment(name="coder")
-env.workspace("workspace")
-```
-
-That alone is a complete environment: any harness that speaks `ssh` - Claude Code, a coding agent,
-your own - can open a shell and edit files in the workspace.
-
-You register capabilities three ways: in the **constructor** for a service that already exists (the
-`ssh` capability in the scaffold above), with **`env.workspace(root)`** for the common shell case, or
-with **`env.add_capability(...)`** from a hook for a daemon the env runs itself (next section). Each
-is concrete wire data - the URL of something serving the protocol. Every protocol has a
-copy-pasteable spin-up in the [Capabilities](/v6/reference/capabilities) reference, with the library that
-backs it.
-
-### Lifecycle hooks: set up and tear down
-
-When a task needs state - seeded files, a running service, a browser - you bring it up in
-`@env.initialize` and release it in `@env.shutdown`. `@env.initialize` runs once before the env
-accepts any connection, so by the time an agent connects, everything it needs is already in place:
-
-```python env.py
-from hud.capabilities import Capability
-
-browser = None
-
-@env.initialize
-async def _up():
-    global browser
-    browser = await launch_chromium()        # bring up whatever the tasks need
-    env.add_capability(Capability.cdp(name="browser", url=f"ws://127.0.0.1:{browser.port}"))
-
-@env.shutdown
-async def _down():
-    if browser is not None:
-        await browser.close()
+env = Environment(name="environment", version="0.0.1", capabilities=None)
 ```
 
-This is also how you publish a daemon you run yourself: start it, then `env.add_capability(...)`.
-It replaces any same-named entry, so re-serving overwrites a stale address rather than duplicating
-it. The full pattern - starting a server task and blocking until it binds - lives in
-[Capabilities](/v6/reference/capabilities#spinning-up-a-capability).
-
-### Tasks: a prompt and a reward
-
-A task is what the agent actually does in the environment, and you register it the same way you
-register everything else - on the object, with a decorator. `@env.template()` turns an async
-generator into a **task template**: it `yield`s a prompt, receives the agent's answer back, and
-`yield`s a reward (`0.0`-`1.0`). Everything the agent does in the environment happens between those
-two yields.
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | `str` | `"environment"` | Environment identity (used as the env-ref name). |
+| `version` | `str` | `"0.0.1"` | Version string surfaced in the manifest. |
+| `capabilities` | `list[Capability] \| None` | `None` | Wire data for services that already exist; see [Capabilities](/v6/reference/capabilities). |
+## Methods
 
-```python env.py
-@env.template()
-async def count_letter(word: str = "strawberry", letter: str = "r"):
-    answer = yield f"How many '{letter}'s are in '{word}'? Reply with just the number."
-    yield 1.0 if answer and str(word.count(letter)) in answer else 0.0   # the reward
-```
+You register capabilities, lifecycle hooks, and tasks against the object with these methods. Each
+becomes part of what the environment advertises when it serves.
 
-A template is generative, not a single task: its parameters (`word`, `letter`) fill in per run, so
-one definition describes a whole *space* of tasks. Calling it - `count_letter(word="raspberry")` -
-binds those arguments and mints one concrete [`Task`](/v6/reference/tasks) you can run. Register as many
-templates as you like on one environment; each is advertised in the manifest, so a harness can
-discover what the environment offers and the orchestrator can pick which to run.
+| Method | Description |
+|--------|-------------|
+| `env.template(*, id=None, description="", input=None, returns=None)` | Register a **task template** (an async generator that yields a prompt, then a reward). Returns a factory that mints a [`Task`](/v6/reference/tasks) when called. |
+| `env.initialize` / `env.shutdown` | Decorators registering hooks run once before serving / on teardown (shutdown runs in reverse order). |
+| `env.add_capability(cap)` | Publish concrete wire data, replacing any same-named entry. Call it from an `@env.initialize` hook once a daemon the env runs is up. |
+| `env.capability(name)` | Look up a published [capability](/v6/reference/capabilities) by name. |
+| `env.workspace(root, *, name="shell", track_files=None, **kwargs)` | Attach a [`Workspace`](/v6/reference/capabilities#workspace) serving `name` over `ssh/2`, wiring its start, publish, and stop lifecycle. File tracking runs by default (`track_files` defaults to `HUD_FILE_TRACKING_ENABLED`). |
+| `env.start()` / `env.stop()` | Run the `@env.initialize` / `@env.shutdown` hooks directly (`start` is idempotent until `stop`). |
+| `env.tasks` / `env.templates` | The registered template factories by id (`templates` is an alias of `tasks`). |
 
-`@env.template()` takes a few optional arguments:
+The `@env.template()` decorator takes optional arguments:
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
@@ -136,41 +51,27 @@ discover what the environment offers and the orchestrator can pick which to run.
 | `input` | `Any` | Optional type for the agent's input (JSON schema in the manifest). |
 | `returns` | `Any` | Optional type the agent must produce; the answer arrives as an `Answer[T]`. See [Types](/v6/reference/types). |
 
-Grading, parameterizing at scale, and collecting tasks into tasksets are their own topic - see
-[Tasks & Tasksets](/v6/reference/tasks).
-
-## The `Environment` object
-
-`hud.environment.Environment` is the lightweight control object the whole file hangs off. When
-served, it acts as the *server* an agent harness connects to over the [protocol](/v6/advanced/protocol):
-it answers `hello` with its capabilities and runs its tasks on request.
-
-```python
-from hud import Environment
-
-env = Environment(name="environment", version="0.0.1", capabilities=None)
-```
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `name` | `str` | `"environment"` | Environment identity (used as the env-ref name). |
-| `version` | `str` | `"0.0.1"` | Version string surfaced in the manifest. |
-| `capabilities` | `list[Capability] \| None` | `None` | Wire data for services that already exist; see [Capabilities](/v6/reference/capabilities). |
-
-<Note>Passing v5-only keywords emits a `DeprecationWarning` and ignores them. See [Migrate to v6](/v6/more/migrate-v6).</Note>
+Grading and collecting tasks into tasksets are their own topics: see [graders](/v6/reference/graders)
+and [Tasks & Tasksets](/v6/reference/tasks).
 
 ## Serving
 
-You rarely serve by hand - `hud eval`, `task.run()`, and `Taskset.run()` bring the environment up for
-you, and the [runtime](/v6/reference/runtime) you pass decides where. Serving itself belongs to
-`hud.environment.server`, the same entry point a container CMD runs
-(`python -m hud.environment.server <source>`):
+You rarely serve by hand - `hud eval`, [`task.run()`](/v6/reference/tasks), and `Taskset.run()` bring
+the environment up for you, and the [runtime](/v6/reference/runtime) you pass decides where. Serving
+itself belongs to `hud.environment.server`, the entry point every substrate runs: a
+[`LocalRuntime`](/v6/reference/runtime#localruntime) child process, a container CMD, or `hud serve`.
 
 | Function | Description |
 |----------|-------------|
-| `await serve(env, host="127.0.0.1", port=0)` | Start daemons and accept control-channel connections (blocks). |
-| `await bind(env, host="127.0.0.1", port=0)` | Bind the socket and return an `asyncio.Server` without serving. |
-| `await env.start()` / `await env.stop()` | Run `@env.initialize` / `@env.shutdown` hooks directly. |
+| `await serve(env, host="127.0.0.1", port=0)` | Start daemons and serve the control channel until cancelled (blocks). |
+| `await bind(env, host="127.0.0.1", port=0)` | Bind the control-channel socket and return an `asyncio.Server` without serving. |
+| `load_environment(path, *, name=None)` | Return the one `Environment` defined at `path` (a `.py` file or directory); `name` selects among several. |
+
+The server module is the same entry point a container CMD runs:
+
+```bash
+python -m hud.environment.server <path> [--env NAME] [--host HOST] [--port PORT]
+```
 
 ```bash
 hud serve env.py     # serve locally on tcp://127.0.0.1:8765 while you iterate
@@ -182,39 +83,6 @@ A dependency that must **own the process main thread** (e.g. Isaac Sim / Omniver
 instead and keep the main thread for the dependency - see [Robots](/v6/advanced/robots#environment-side).
 </Note>
 
-## Learn from real environments
-
-The fastest way to internalize the patterns is to read complete ones. Each cookbook walks an `env.py`
-end to end:
-
-<CardGroup cols={2}>
-<Card title="Coding agent" icon="code" href="/v6/cookbooks/coding-agent">
-  A shell + files env that grades a test suite.
-</Card>
-<Card title="Ops diagnostics" icon="terminal" href="/v6/cookbooks/ops-diagnostics">
-  Seed state in `@env.initialize`, grade by inspection.
-</Card>
-<Card title="Robot benchmark" icon="robot" href="/v6/cookbooks/robot-benchmark">
-  A simulator env over the `robot` capability.
-</Card>
-<Card title="More on GitHub" icon="github" href="https://github.com/hud-evals/hud-python/tree/main/cookbooks">
-  Full, runnable environments in the SDK repo.
-</Card>
-</CardGroup>
-
-## See also
-
-<CardGroup cols={2}>
-<Card title="Capabilities" icon="plug" href="/v6/reference/capabilities">
-  Every protocol factory, its params, and how to spin it up.
-</Card>
-<Card title="Tasks & Tasksets" icon="list-check" href="/v6/reference/tasks">
-  Add tasks that prompt and grade against this environment.
-</Card>
-<Card title="Runtime" icon="server" href="/v6/reference/runtime">
-  Point a harness at your environment and run it anywhere.
-</Card>
-<Card title="Composing richer environments" icon="layer-group" href="/v6/advanced/extending">
-  Multi-capability envs, stateful daemons, and custom setups.
-</Card>
-</CardGroup>
+See [creating an environment](/v6/guides/creating-an-environment) to author one,
+[capabilities](/v6/reference/capabilities) for the access it exposes, and [runtime](/v6/reference/runtime)
+for where it runs.
diff --git a/docs/v6/reference/graders.mdx b/docs/v6/reference/graders.mdx
index 63a35393..c1da269c 100644
--- a/docs/v6/reference/graders.mdx
+++ b/docs/v6/reference/graders.mdx
@@ -16,6 +16,27 @@ from hud.graders import (
 )
 ```
 
+## What grading scores
+
+Grading decides *what* the reward measures. Two framings cover most tasks:
+
+- **Grade the answer** - compute a float from what the agent said.
+- **Grade the world** - score the state the agent left behind: tests passing, a file written, a
+  service responding. Because the agent acts on a real system through its
+  [capabilities](/v6/reference/capabilities), this is **outcome verification**: the rigor of a test
+  suite with no fixed protocol the agent has to follow.
+
+## Approaches
+
+Three approaches cover grading, in increasing power. Each produces the `float` or
+[`EvaluationResult`](#subscore-and-evaluationresult) yielded as the task's second yield.
+
+| Approach | When to reach for it | Example |
+|----------|----------------------|---------|
+| **Plain Python** | A reward you compute from the answer, optionally via a comparison helper | `yield numeric_match(answer, 3)` |
+| **Async grader** | Score a command's exit code or an LLM's judgment of the answer | `yield (await BashGrader.grade(weight=1.0, command="pytest -q")).value` |
+| **Composed** | Weight several graders into one reward, each subscore kept in the trace | `yield await combine(BashGrader.grade(...), LLMJudgeGrader.grade(...))` |
+
 ## Comparison helpers
 
 Each returns a `float` (`0.0`-`1.0`) you can yield directly or wrap in a `SubScore`.
@@ -72,7 +93,8 @@ result = await LLMJudgeGrader.grade(
 )
 ```
 
-`criteria` items are strings, or `(requirement, weight)` tuples.
+`criteria` items are strings, or `(requirement, weight)` tuples. A negative weight marks an error to
+avoid: the criterion scores as a penalty, MET when the answer actually makes the mistake.
 
 ## `combine` - compose multiple graders
 
@@ -129,9 +151,5 @@ An `EvaluationResult` is the combined grade payload you can yield from a task:
 
 `EvaluationResult.from_float(value)` wraps a bare reward.
 
-## See also
-
-<CardGroup cols={2}>
-<Card title="Tasks & Tasksets" icon="list-check" href="/v6/reference/tasks" />
-<Card title="Designing tasks" icon="signal" href="/v6/reference/advice" />
-</CardGroup>
+Graders run as the second yield of a [task](/v6/reference/tasks); for choosing a reward that separates
+good work from bad, see [designing tasks](/v6/reference/advice).
diff --git a/docs/v6/reference/runtime.mdx b/docs/v6/reference/runtime.mdx
index 479ea37a..1a20ec4c 100644
--- a/docs/v6/reference/runtime.mdx
+++ b/docs/v6/reference/runtime.mdx
@@ -1,29 +1,19 @@
 ---
 title: "Runtimes"
-description: "Run a task by deploying to the platform or programmatically from your machine."
+description: "Where each rollout's environment runs - the runtime you pass at execution time."
 icon: "rocket"
 ---
 
-This page covers how you actually run tasks: deploying an environment to the HUD platform, and running
-it programmatically from your own machine. Both go through a **runtime** - the one thing you pass to
-choose where each rollout runs.
-
-## Runtime
-
-A **runtime** decides *where* an environment runs for a rollout. You pass it to `task.run` /
+A **runtime** chooses where each rollout's environment runs. You pass it to `task.run` /
 `taskset.run` at execution time, and the same task and the same `env.py` run anywhere - only the
 runtime changes.
 
 ```python
 from hud.eval import LocalRuntime
 
-await TASKS.run(agent, runtime=LocalRuntime("env.py"))   # serve env.py locally, run here
+await taskset.run(agent, runtime=LocalRuntime("env.py"))   # serve env.py locally, run here
 ```
 
-Under the hood a runtime is just a function: given a task, bring the environment up somewhere and hand
-back its control-channel URL. The agent loop always runs on your machine and drives that URL; the
-runtime only decides what's on the other end.
-
 ## Built-in runtimes
 
 | Runtime | Where the env runs | When to reach for it |
@@ -33,49 +23,28 @@ runtime only decides what's on the other end.
 | `ModalRuntime("my-env")` | A fresh [Modal](https://modal.com/) sandbox per rollout | Cloud scale, no infra to manage |
 | `DaytonaRuntime("my-env")` | A fresh [Daytona](https://www.daytona.io/) sandbox per rollout | Cloud scale on Daytona |
 | `Runtime("tcp://host:8765")` | A substrate you already started | Attaching to a long-lived container or sandbox you own |
-| `HUDRuntime()` | The HUD platform, leased by name | After you deploy (see below); the default when `runtime=` is omitted for platform/file rows |
+| `HUDRuntime()` | A HUD-hosted env, leased by name and tunneled | Local agent loop against a deployed env |
+| `HostedRuntime()` | The whole rollout on a HUD-leased box | Agent and env run together off your machine |
 
 Most runtimes are on the top-level package (`from hud import LocalRuntime, DockerRuntime, HUDRuntime,
-Runtime`); `ModalRuntime` and `DaytonaRuntime` import from `hud.eval`.
+HostedRuntime, Runtime`); `ModalRuntime` and `DaytonaRuntime` import from `hud.eval`.
 
 <Note>
-**Omit `runtime=` and it's inferred.** A taskset minted in-process from one `.py` source serves that
-source locally; rows loaded from a file or the platform fall back to `HUDRuntime`. Pass a runtime
-explicitly the moment you want something other than that.
+**Omit `runtime=` and it's inferred** from each task's `_source`, the file its template was defined
+in. When every task shares one `_source`, that source is served locally as `LocalRuntime(source)`;
+otherwise (mixed sources, or rows loaded from a file or the platform with no source) it falls back to
+`HUDRuntime()`. Pass a runtime explicitly the moment you want something else.
 </Note>
 
-## The decision: run it yourself or deploy
-
-Every runtime above is one of two choices, and that choice is the only one that really matters: do you
-keep the environment on infra **you** bring up, or **deploy** it to the HUD platform?
-
-- **Run it yourself.** `LocalRuntime` for development, `DockerRuntime` for a reproducible container,
-  `ModalRuntime` / `DaytonaRuntime` for cloud sandboxes, or `Runtime(url)` to attach to something you
-  already started. You own the substrate's lifecycle.
-- **Deploy to the platform.** `hud deploy` builds your environment image and hosts it; then
-  `HUDRuntime()` leases it per rollout while your agent loop stays local. This is the path to running
-  batches and comparing models from the [platform UI](https://hud.ai), with every trace browsable.
-
-## Package & deploy
-
-Deploying builds your environment into an **image** on HUD and registers it by the name in your
-`Environment(...)` declaration - one step, no local Docker:
-
-```bash
-hud deploy                 # build the image on HUD from Dockerfile.hud, register it by name
-hud sync tasks my-taskset  # publish the taskset (uploads only what changed)
-```
-
-`hud init` scaffolds the `Dockerfile.hud`. One build packs every task from the definition, so the same
-image runs unchanged on HUD, on a cloud sandbox, in CI, or on your laptop. After deploying,
-`HUDRuntime()` is the natural pair. Pass build config with `--env`, `--build-arg`, and `--secret`. See
-the [CLI reference](/v6/reference/cli#hud-deploy) for the full flag set.
+To deploy an environment to the platform and run against it, see
+[running an eval](/v6/guides/running-an-eval) and
+[deploying to the platform](/v6/guides/creating-an-environment#deploying-to-the-platform).
 
 ## RuntimeConfig
 
 `RuntimeConfig` carries the construction hints a container-based runtime needs: which image, how much
 hardware, and what timeouts. Set it on the runtime (`runtime_config=`) or per row on
-[`Task.runtime_config`](/v6/reference/tasks#the-task-row); the runtime merges the two and applies what it
+[`Task.runtime_config`](/v6/reference/tasks#task); the runtime merges the two and applies what it
 supports.
 
 ```python
@@ -126,12 +95,13 @@ DockerRuntime(image=None, *, port=8765, run_args=(), runtime_config=None)
 ### `ModalRuntime`
 
 ```python
-ModalRuntime(image_name=None, *, image=None, command=None, app_name="hud-envs", port=8765, runtime_config=None, env_vars=None)
+ModalRuntime(image_name=None, *, image=None, command=None, app_name="hud-envs", workdir=None, port=8765, runtime_config=None, env_vars=None)
 ```
 
 - **`image_name`** - published Modal image name (the preferred durable handle), e.g. `ModalRuntime("hud-libero-env")`.
 - **`image`** - an `Image` to build lazily on first use, as an escape hatch.
 - **`command`** - override the serving command (defaults to the scaffolded `hud serve` entrypoint).
+- **`workdir`** - working directory inside the sandbox. Left unset, Modal keeps the image's `WORKDIR`.
 - **`app_name`** / **`port`** / **`env_vars`** - Modal app name, in-sandbox serving port, and extra environment variables.
 
 Requires the `modal` extra and a configured token.
@@ -158,6 +128,20 @@ HUDRuntime(*, run_timeout=3600.0, runtime_url=None)
 
 The SDK leases your deployed env by name and tunnels to its control channel; the agent loop runs local.
 
+### `HostedRuntime`
+
+```python
+HostedRuntime(*, poll_interval=5.0, run_timeout=3600.0)
+```
+
+- **`poll_interval`** - seconds between trace-status polls while the rollout runs remotely.
+- **`run_timeout`** - bound on one rollout end to end, including instance provisioning and queueing.
+
+Where `HUDRuntime` runs the agent loop locally against a tunneled env, `HostedRuntime` runs the
+**whole rollout** off-box: the platform leases an instance, brings the env's container up on it, and
+runs the agent right next to it. This process only submits the rollout and polls its trace to
+completion. It requires a gateway agent that can serialize its identity (Claude/OpenAI/Gemini).
+
 ### `Runtime`
 
 ```python
@@ -185,7 +169,7 @@ async def my_runtime(task):
     finally:
         await sandbox.terminate()                       # ...and tears it down
 
-await TASKS.run(agent, runtime=my_runtime)
+await taskset.run(agent, runtime=my_runtime)
 ```
 
 `DockerRuntime` and the rest are just built-in versions of this. Anything that starts your image and
diff --git a/docs/v6/reference/tasks.mdx b/docs/v6/reference/tasks.mdx
index 2c5898bd..55e871e8 100644
--- a/docs/v6/reference/tasks.mdx
+++ b/docs/v6/reference/tasks.mdx
@@ -4,19 +4,23 @@ description: "What a task is, how you define one, and how a single definition be
 icon: "list-check"
 ---
 
-An [environment](/v6/reference/environment) is *where* the agent acts. A **task** is the *work* you measure
-there. A task only ever does two things: it **prompts** the agent, and it **grades** what happened into
-a single number, the **reward**. That one number is the whole point - it's what an evaluation reports
-and what [training](/v6/reference/training) learns from.
-
-Four words do all the work, and they're worth keeping apart:
-
-- a **template** is the generator you author with `@env.template()`. It's callable, and calling it
-  doesn't run anything - it *mints* a task.
-- a **task** is a filled-in template: one set of arguments bound into a single runnable row (the
-  environment name, the template id, the args). You `run` a task.
-- a **taskset** is a named, ordered collection of tasks - a table of those rows.
-- a **job** is the receipt a run produces: the graded runs and their mean reward.
+An [environment](/v6/reference/environment) is *where* the agent acts. A **task** is the *work* you
+measure there: the unit of evaluation, one prompt paired with one graded outcome that resolves to a
+single number, the **reward**. That one number is what an evaluation reports and what
+[training](/v6/reference/training) learns from.
+
+A task has two representations. You author it as an **async generator** decorated with `@env.template`,
+the shape that prompts the agent and scores what happens. Calling that template mints a **`Task`**: a
+plain data row (an env name, a template id, bound args) that travels over the wire and runs anywhere.
+The agent loop and grading happen in the gap between the generator's two yields, and a call to
+[`run()`](#running) executes one row and returns a [`Job`](/v6/reference/types#job).
+
+| Concept | What it is |
+| --- | --- |
+| **Template** | The async generator you author with `@env.template`. Callable; calling it mints a task without running anything. |
+| **Task** | A filled-in template: one set of arguments bound into a single runnable [row](#task). |
+| **Taskset** | A named, ordered collection of tasks - a table of those rows. |
+| [**Job**](/v6/reference/types#job) | The receipt a run produces: the graded runs and their mean reward. |
 
 ## Defining a task
 
@@ -39,20 +43,33 @@ This shape is deliberate. Everything the agent does - every step, tool call, and
 in the gap between the two yields, so you describe a task as plain Python: ask on one line, score on the
 next. The agent loop in the middle is HUD's job, not yours.
 
-`@env.template()` registers the generator as a template; calling it mints a concrete `Task`:
+The second yield can be a bare `float`, an [`EvaluationResult`](/v6/reference/graders#subscore-and-evaluationresult),
+or a dict with a numeric `score`; the env layer normalizes any of them to the reward.
+
+## Template
+
+`@env.template()` registers the generator as a **template**: a callable that mints a concrete `Task`
+without running anything.
 
 ```python
 task = count_letter(word="raspberry")   # a Task row, not yet run
 ```
 
-Declare `returns=T` on the template and the answer arrives as a parsed
-[`Answer[T]`](/v6/reference/types) (`.content` parsed, `.raw` the original string); without it, `answer` is
-the raw string the agent submitted.
+It takes four optional arguments:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | `str \| None` | Task id registered on the environment. Defaults to the function name. |
+| `description` | `str` | Human-readable summary surfaced in the manifest. Defaults to `""`. |
+| `input` | `Any` | Type declaring the template's arguments; surfaced in the manifest as a JSON schema. |
+| `returns` | `Any` | Type declaring the agent's answer; surfaced in the manifest and parses the answer into a typed [`Answer[T]`](/v6/reference/types). |
 
-## One definition, many tasks
+Declare `returns=T` and the answer arrives as a parsed [`Answer[T]`](/v6/reference/types#typed-task-io)
+(`.content` parsed, `.raw` the original string); without it, `answer` is the raw string the agent
+submitted.
 
-The core move: one template spans a *space* of tasks. Call it with different arguments and a single
-function becomes a whole dataset, with no separate artifact per task:
+One template spans a *space* of tasks. Call it with different arguments and a single function becomes a
+whole dataset, with no separate artifact per task:
 
 ```python tasks.py
 tasks = [count_letter(word=w) for w in ("strawberry", "raspberry", "blueberry")]
@@ -60,7 +77,7 @@ tasks = [count_letter(word=w) for w in ("strawberry", "raspberry", "blueberry")]
 
 Parameterize across difficulties, inputs, or seeds and one definition becomes an entire benchmark.
 
-## The Task row
+## Task
 
 A `Task` is a Pydantic model - one portable, validated row of data. It holds no live environment: `env`
 is a *name*, the join key between the row and whatever brings that environment up at run time. So a task
@@ -89,70 +106,9 @@ task = Task(env="letter-count", id="count_letter", args={"word": "strawberry"},
 
 ## Grading
 
-The second yield is the reward. The first decision is *what* you score:
-
-- **Grade the answer** - compute a float from what the agent said.
-- **Grade the world** - score the **state the agent left behind**: tests passing, a file written, a
-  service responding. Because the agent acts on a real system through its
-  [capabilities](/v6/reference/capabilities), this is often the most reliable signal. It's **outcome
-  verification**: the rigor of a test suite, with no fixed protocol the agent has to follow.
-
-You reach for one of three approaches, in increasing power:
-
-<AccordionGroup>
-
-<Accordion title="1. Plain Python - compute a float yourself">
-For simple checks, just return a number. HUD ships normalized comparison helpers in `hud.graders`:
-
-```python tasks.py
-from hud.graders import numeric_match
-
-@env.template()
-async def count_letter(word: str = "strawberry", letter: str = "r"):
-    answer = yield f"How many '{letter}'s are in '{word}'?"
-    yield numeric_match(answer, word.count(letter))
-```
-
-Helpers include `exact_match`, `contains`, `numeric_match`, `f1_score`, and `normalize` - each returns a `float`.
-</Accordion>
-
-<Accordion title="2. Async graders - score a command or an LLM judgment">
-`BashGrader` runs a shell command and scores by exit code; `LLMJudgeGrader` scores an answer against
-rubric criteria. This is also how you **grade the world** - point a command at the state the agent left:
-
-```python tasks.py
-from hud.graders import BashGrader
-
-@env.template()
-async def add_endpoint():
-    yield "Add a /health endpoint to the app in your workspace and make it return 200."
-    result = await BashGrader.grade(command="pytest tests/test_health.py -q")
-    yield result.value   # score what the agent did, not how it described it
-```
-</Accordion>
-
-<Accordion title="3. Composed graders - combine several into one reward">
-`combine` runs several graders in parallel and weights them into one reward, with each subscore visible
-in the trace so a partial reward is legible:
-
-```python tasks.py
-from hud.graders import BashGrader, LLMJudgeGrader, combine
-
-@env.template()
-async def implement_feature(spec: str = "add a /health endpoint"):
-    answer = yield f"Implement this and summarize what you changed: {spec}"
-    yield await combine(
-        BashGrader.grade(weight=0.5, command="pytest -q"),
-        LLMJudgeGrader.grade(weight=0.5, answer=answer, criteria=["Matches the spec"]),
-    )
-```
-</Accordion>
-
-</AccordionGroup>
-
-The full catalog lives in the [Graders reference](/v6/reference/graders). A grader that returns a constant
-or just echoes the answer back teaches a model nothing and invites reward hacking; a good reward
-separates good work from bad - see [Designing tasks](/v6/reference/advice).
+The second yield is the reward. Return a float inline, or reach for the comparison helpers, async
+graders, and composed grades documented in [graders](/v6/reference/graders). For how to design a reward
+that separates good work from bad and resists hacking, see [designing tasks](/v6/reference/advice).
 
 ## Tasksets
 
@@ -185,69 +141,35 @@ collections:
 
 ## Running
 
-`taskset.run(agent, ...)` executes every task and returns a [`Job`](#jobs). `task.run(...)` is the same
-call over a taskset of one, with identical semantics:
+`taskset.run(agent, ...)` executes every task and returns a [`Job`](/v6/reference/types#job).
+`task.run(...)` is the same call over a taskset of one, with identical semantics.
 
 ```python
 from hud import LocalRuntime
 
-# one task
-job = await count_letter(word="strawberry").run(agent, runtime=LocalRuntime("env.py"))
-
-# a whole taskset: 8 rollouts per task, capped concurrency
 job = await ts.run(agent, runtime=LocalRuntime("env.py"), group=8, max_concurrent=10)
-print(job.reward)
 ```
 
-- **`runtime=`** chooses *where* each rollout runs (local subprocess, container, cloud sandbox, HUD).
-  Swap it freely without touching the tasks; omit it and placement is inferred (a locally-authored
-  source serves itself, platform/file rows go HUD-hosted). See [Runtime](/v6/reference/runtime).
-- **`group=`** repeats each task N times so you can see the reward spread (the grouping GRPO trains on).
-- **`max_concurrent=`** caps how many rollouts run in parallel.
-
-A crashed rollout comes back as a failed `Run` inside the job rather than raising, so one bad rollout
-never collapses a batch.
-
-## Jobs
-
-A `Job` is the receipt for one execution. Every run reports under a job - there are no standalone
-traces, so even a single `task.run` returns a job of one.
-
-| Member | Type | Description |
-|--------|------|-------------|
-| `id` | `str` | HUD job id. |
-| `name` | `str` | Display name. |
-| `runs` | `list[Run]` | The graded [`Run`](/v6/reference/types#run)s, in expansion order. |
-| `group` | `int` | Rollouts per task. |
-| `reward` | `float` | Mean reward across all runs. |
-| `results` | `dict[str, list[Run]]` | Runs grouped by task slug - the alignment-safe alternative to `zip(tasks, runs)` (list-valued since `group > 1` gives several runs per task). |
-
-```python
-job = await ts.run(agent, runtime=LocalRuntime("env.py"), group=4)
-job.reward                          # mean across every run
-job.runs[0].trace.content           # what the agent answered on the first run
-for slug, runs in job.results.items():   # per-task: its runs, keyed by slug
-    print(slug, sum(r.reward for r in runs) / len(runs))
-```
-
-By default each `run` call mints its own job. To gather many calls under one id - a training session, a
-multi-turn chat - open one with `Job.start` and pass it as `job=`:
-
-```python
-from hud import Job
-
-job = await Job.start("grpo-session", group=8)
-for step in range(epochs):
-    await ts.run(agent, runtime=LocalRuntime("env.py"), job=job)   # all runs accumulate here
-```
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `agent` | `Agent` | The shared, stateless agent driven across every rollout. |
+| `runtime` | `Provider \| HostedRuntime \| None` | Where each rollout runs; omit it and placement is inferred (local source serves itself, else the HUD tunnel by env name). See [runtime](/v6/reference/runtime). |
+| `group` | `int \| None` | Repeats each task N times for the reward spread GRPO trains on. |
+| `max_concurrent` | `int \| None` | Caps how many rollouts run in parallel. |
+| `job` | `Job \| None` | An open [`Job`](/v6/reference/types#job) to accumulate into; defaults to a fresh job per call. |
+| `rollout_timeout` | `float \| None` | Per-rollout wall-clock cap (seconds) on the local path; a breach is recorded as a failed run. |
 
-## Syncing to the platform
+A crashed rollout comes back as a failed [`Run`](/v6/reference/types#run) inside the job rather than
+raising, so one bad rollout never collapses a batch. For the end-to-end workflow see
+[running an eval](/v6/guides/running-an-eval).
 
-Sync is only for the platform: it publishes a locally-authored taskset to [hud.ai](https://hud.ai) so
-you can run it there, compare models on it, and browse its traces. Local runs never need it.
+## Syncing
 
-`hud sync tasks <name>` uploads a taskset and only what changed. In code, `diff()` shows that
-comparison as a `SyncPlan`:
+Sync publishes a locally-authored taskset to [hud.ai](https://hud.ai) so you can run it there, compare
+models on it, and browse its traces; local runs never need it. The `hud sync tasks <name>` command
+uploads a taskset and only what changed, a workflow covered in
+[creating an environment](/v6/guides/creating-an-environment#deploying-to-the-platform). In code,
+`diff(local, remote)` returns a `SyncPlan` describing the comparison:
 
 ```python
 from hud.eval.sync import diff
@@ -263,19 +185,6 @@ print(plan.summary())
 | `unchanged` | Local tasks that match remote. |
 | `remote_only` | Remote tasks with no local counterpart. |
 
-## See also
-
-<CardGroup cols={2}>
-<Card title="Environments" icon="cube" href="/v6/reference/environment">
-  Where the agent acts, and the capabilities a task grades against.
-</Card>
-<Card title="Graders" icon="check-double" href="/v6/reference/graders">
-  Every grader, comparison helper, and the `combine` combiner.
-</Card>
-<Card title="Runtime" icon="server" href="/v6/reference/runtime">
-  Where each task runs, chosen at execution time.
-</Card>
-<Card title="Designing tasks" icon="lightbulb" href="/v6/reference/advice">
-  Design tasks that actually teach: difficulty, spread, and resisting reward hacking.
-</Card>
-</CardGroup>
+Once a reward separates good work from bad, [designing tasks](/v6/reference/advice) covers the
+difficulty and spread that make a taskset worth training on, and [graders](/v6/reference/graders) the
+scoring that produces each reward.
diff --git a/docs/v6/reference/training.mdx b/docs/v6/reference/training.mdx
index 6c2cdf49..6ae60c78 100644
--- a/docs/v6/reference/training.mdx
+++ b/docs/v6/reference/training.mdx
@@ -1,122 +1,42 @@
 ---
 title: "Training"
-description: "Turn the rewards you already collect into an improving model: the loop, the TrainingClient API, losses, and the hud models CLI."
+description: "The TrainingClient API, training paths, losses, results, and the hud models CLI."
 icon: "dumbbell"
+mode: "wide"
 ---
 
-The key idea: **the rewards you collect are already training data.** Every rollout produced a
-trajectory (what the agent did) and a [reward](/v6/reference/tasks) (how well it did). Training nudges the
-model's weights so the behavior that earned *high* reward becomes more likely next time. You feed that
-signal into **HUD's managed trainer** (the simple path, no ML infra) or into **your own** RL loop.
+Training advances a model's weights from the rewards a rollout already produces. A
+[`TrainingClient`](#trainingclient) drives the managed path against one model slug; lower-level methods
+expose the gradient-accumulation and custom-loss steps underneath it. For the end-to-end loop (forking a
+model, rolling out a taskset in groups, feeding rewards back) see [training agents](/v6/guides/training-agents).
 
-## Training is a loop
+## Training paths
 
-All of training is one loop repeated:
+Each path accumulates gradients differently, then applies them with the same `optim_step`. All operate on
+a [`TrainingClient`](#trainingclient) except the last.
 
-1. **Roll out** a batch of tasks with the current model.
-2. **Score** each rollout - that's the reward you already get for free.
-3. **Nudge** the model's weights toward the rollouts that scored better.
-4. **Repeat** - the next batch samples the now-slightly-better model.
+| Path | How gradients accumulate | Promote weights |
+| --- | --- | --- |
+| Managed one-shot | `step(trajectories, learning_rate=...)` | folded into `step` |
+| Split accumulate then update | `forward_backward(...)` once or repeated (or `num_substeps>1`) | `optim_step(...)` |
+| Client-side custom loss | `forward_backward_custom(trajectories, loss_fn)` | `optim_step(...)` |
+| Low-level | `forward(...)` then your loss then `backward(forward_id, weights)` | `optim_step(...)` |
+| Supervised (SFT) | any path with `loss_fn="cross_entropy"` (`BuiltinLoss.CROSS_ENTROPY`) | as above |
+| External RL stack | export each [`Run`](/v6/reference/types#run)'s `reward` and `trace_id`; no `TrainingClient` | owned by your stack |
 
-```mermaid
-flowchart LR
-    A([roll out tasks]) --> B([collect rewards]) --> C([nudge weights]) --> A
-```
-
-Each pass makes the model a little better at the tasks you're training on. Everything below is how you
-set that loop up.
-
-## What you need first
-
-- **A task with spread in its rewards.** This is the one prerequisite people miss. If every rollout of
-  a task gets the *same* reward, training learns nothing from it (see [Why grouping
-  matters](#why-grouping-matters)). Designing tasks that produce spread is its own craft - see
-  [Designing tasks](/v6/reference/advice).
-- **A trainable model**, which you make by forking one (next).
-
-## Get a trainable model
-
-Only some gateway models can be trained. List what's available and fork one into your own private,
-team-owned model whose weights you're allowed to advance:
-
-```bash
-hud models list                              # the Trainable column marks forkable bases
-hud models fork Qwen/Qwen3.5-4B --name arith-rl
-```
-
-The new slug (`arith-rl`) is both what you **sample** (like any other model) and what you **train**.
-The fork starts from the base's current weights, so you continue from where it left off.
-
-## Run the loop
-
-This is the whole thing. Each step: roll out a batch with the current model, hand those graded rollouts
-to the trainer, and it nudges the weights. The next step then samples the improved model.
-
-```python train.py
-from hud import TrainingClient
-from hud.agents import create_agent
-from hud.eval import Job
-
-# return_token_ids tells the gateway to send back the token ids + logprobs training needs
-agent = create_agent("arith-rl", completion_kwargs={"extra_body": {"return_token_ids": True}})
-trainer = TrainingClient("arith-rl")
-taskset, runtime = ...   # your taskset + where rollouts run (see Tasks / Run & deploy)
-
-session = await Job.start("arith-rl", group=8)   # 8 rollouts per task
-for _ in range(10):
-    start = len(session.runs)
-    await taskset.run(agent, runtime=runtime, job=session)   # roll out a batch
-    batch = session.runs[start:]
-    await trainer.step(batch, learning_rate=1e-5, group_size=8)   # nudge the weights
-```
-
-The one line that learns is `trainer.step(...)`. It computes how each rollout should shift the weights,
-applies that shift, then checkpoints and **promotes** the new weights so the gateway serves them
-immediately. That's why the *next* `taskset.run` samples an improved model - the loop closes itself.
-
-The trainer's input is the rewards you already have: a [`Job`](/v6/reference/tasks#jobs) holds the graded
-[`Run`](/v6/reference/types#run)s from each batch, and you pass those runs (or a slice) straight to
-`trainer.step`. Each `Run` carries its reward and either inline token samples or a `trace_id`, which is
-all the trainer needs (see [Inputs](#inputs)).
-
-## Why grouping matters
+Gradients accumulate across `forward_backward` / `forward_backward_custom` / `backward` calls until an
+`optim_step` (or `step`, which calls both) applies them, checkpoints, and promotes the new weights.
 
-The one concept worth really understanding. HUD trains with **GRPO**, which scores each rollout
-*relative to its group*: an advantage of `reward - group_mean`. So a rollout is "good" only by
-comparison to its siblings on the same task.
+## Objects
 
-The consequence: if every rollout in a group earns the **same** reward, every advantage is zero and
-**no learning happens** - no matter how high the average looks. That's why you run each task as a group
-(`group=8` above) and why your tasks must produce a **spread** of rewards. Trainability is a property of
-your tasks, not just your loop - the whole point of [Designing tasks](/v6/reference/advice).
-
-## Watch it improve
-
-Each step adds a node to the model's **checkpoint tree** and promotes it to the **head** - the weights
-the gateway now serves. A node carries everything you need to watch a run: `mean_reward`, `loss_fn`,
-token/datum counts, and a `metrics` blob (reward spread, sampling logprob, provider training stats like
-PPO KL and clip fraction). Read it from the shell or from the loop:
-
-```bash
-hud models checkpoints arith-rl          # the checkpoint tree (active head marked)
-hud models head arith-rl --set <id>      # roll back or branch from an earlier point
-```
-
-```python
-for c in await trainer.checkpoints():    # same data, in the training loop
-    print(c.name, c.mean_reward, c.metrics.get("reward_std"))
-```
-
-Setting the head points the gateway at a different checkpoint and the next `optim_step` extends the tree
-from there - so a checkpoint is also a **rollback point**.
-
-<Warning>
-Roll back when the objective changes. If you edit the reward function or the environment partway through
-a run, the current head encodes the *old* objective - continuing from it fine-tunes a contaminated
-policy, and the early steps after the change mostly undo the old shaping. Roll the head back to a
-checkpoint from before the change (`set_head` / `--set`), or fork a fresh model, so the run measures the
-new objective from a clean start.
-</Warning>
+| Object | Role |
+| --- | --- |
+| Forked model slug | The gateway string you both sample and train; weights advance behind it in place. |
+| [`create_agent`](/v6/reference/agents#create-agent) `completion_kwargs` | Marks rollouts for token capture (`extra_body={"return_token_ids": True}`); OpenAIChatConfig-only (see [Token capture](#token-capture)). |
+| [`Job`](/v6/reference/types#job) / `group` | The receipt collecting a batch's graded [`Run`](/v6/reference/types#run)s; `group` sets rollouts per task, the GRPO group. |
+| [`Run`](/v6/reference/types#run) | One graded rollout; carries its `reward` and either inline token samples or a `trace_id`. |
+| `TrainingClient` | Drives managed training for one model slug. |
+| `CheckpointResponse` | One node in the model's checkpoint tree. |
 
 ## TrainingClient
 
@@ -141,7 +61,7 @@ TrainingClient(model, *, api_key=None, base_url=None, api_url=None)
 |--------|---------|---------|
 | `forward_backward(trajectories, *, loss_fn, loss_fn_config=None, group_size=None, reward_scale=1.0, num_substeps=1)` | `ForwardBackwardResult` | Accumulate gradients with a built-in `loss_fn`. |
 | `optim_step(*, learning_rate, beta1=0.9, beta2=0.95, eps=1e-8, weight_decay=0.0)` | `OptimStepResult` | Apply gradients, checkpoint, and promote the new weights. |
-| `step(trajectories, *, learning_rate, ...)` | `OptimStepResult` | One `forward_backward` then one `optim_step`. |
+| `step(trajectories, *, learning_rate, loss_fn="importance_sampling", loss_fn_config=None, group_size=None, reward_scale=1.0, num_substeps=1, weight_decay=0.0)` | `OptimStepResult` | One `forward_backward` then one `optim_step`. |
 | `forward_backward_custom(trajectories, loss_fn, *, group_size=None, reward_scale=1.0)` | `ForwardBackwardResult` | Accumulate gradients with a client-side loss (see [Custom losses](#custom-losses)). |
 | `forward(trajectories, *, group_size=None, reward_scale=1.0)` | `ForwardResult` | Current-policy forward pass returning per-token tensors. |
 | `backward(forward_id, weights, *, metrics=None)` | `ForwardBackwardResult` | Apply caller-computed per-token gradients to a forward pass. |
@@ -150,9 +70,11 @@ TrainingClient(model, *, api_key=None, base_url=None, api_url=None)
 | `head()` | `CheckpointResponse \| None` | The active checkpoint (the weights the gateway serves), or `None` for base weights. |
 | `set_head(checkpoint_id)` | `None` | Promote a checkpoint to head - roll back to, or branch from, it. |
 
-Advantages are normalized within contiguous **groups** of `group_size` (GRPO); `None` treats the whole
-batch as one group. The batch must divide evenly into groups - `forward_backward` rejects a partial
-final group before spending a forward pass. `num_substeps` splits the batch for gradient accumulation.
+Advantages are group-relative (GRPO-style) when `group_size` is set, normalized within contiguous
+**groups** of that size; `None` treats the whole batch as one group. The `loss_fn` selects the
+policy-gradient objective applied on top, defaulting to `importance_sampling` (not GRPO itself). The
+batch must divide evenly into groups - `forward_backward` rejects a partial final group before spending
+a forward pass. `num_substeps` splits the batch for gradient accumulation.
 
 ## Inputs
 
@@ -169,11 +91,28 @@ e.g. an opponent move sampled inside the environment during self-play, trained w
 
 | Type | Fields |
 |------|--------|
-| `TrajectorySample` | `prompt_token_ids`, `output_token_ids`, `output_logprobs` |
+| `TrajectorySample` | `prompt_token_ids`, `prompt_chunks`, `output_token_ids`, `output_logprobs` |
 | `TrajectoryPayload` | `samples: list[TrajectorySample]`, `reward`, `trace_id=None` |
 
-To get the token data for a hand-built payload, ask the gateway for it on the completion call: pass
-`extra_body={"return_token_ids": True}` with `logprobs=True`, then read the ids off the choice.
+A sample's prompt is `prompt_token_ids` for a flat text prompt, or `prompt_chunks` (serialized text +
+image chunks) for a multimodal one, where `prompt_token_ids` is empty. `output_logprobs` are per output
+token under the sampling policy.
+
+### Token capture
+
+The token ids and logprobs a sample needs come from the gateway. `completion_kwargs` carries the flag,
+and it lives only on `OpenAIChatConfig`, so token capture runs through `OpenAIChatAgent` (the agent
+[`create_agent`](/v6/reference/agents#create-agent) selects for gateway models routed over Chat
+Completions). Setting `extra_body={"return_token_ids": True}` is enough: that agent sets `logprobs=True`
+automatically and writes a `Sample` onto each turn, which a `Run` converts to a `TrajectoryPayload` for
+training.
+
+```python
+agent = create_agent("arith-rl", completion_kwargs={"extra_body": {"return_token_ids": True}})
+```
+
+Calling the gateway directly with your own OpenAI client (for a hand-built payload) takes both flags,
+since nothing sets `logprobs` for you:
 
 ```python
 resp = await client.chat.completions.create(
@@ -222,9 +161,13 @@ def my_loss(data: list[DatumTensors], logprobs: list[torch.Tensor]):
         loss = loss - (ratio * datum.reward * torch.tensor(datum.mask)).sum()
     return loss, {"trained": float(len(data))}
 
-await trainer.forward_backward_custom(batch, my_loss, group_size=8)
+await trainer.forward_backward_custom(batch, my_loss, group_size=8)   # accumulate gradients
+await trainer.optim_step(learning_rate=1e-5)                          # apply, checkpoint, promote
 ```
 
+Gradients accumulate on the model session until `optim_step` applies them, so a custom-loss step is not
+complete until that call promotes the new weights.
+
 `logprobs[i]` are the current policy for datum `i` as differentiable leaves. Everything else is constant
 on the matching `DatumTensors`:
 
@@ -244,7 +187,7 @@ Under the hood `forward` returns a `ForwardResult` (`forward_id` + `data: list[D
 |------|--------|
 | `ForwardBackwardResult` | `metrics: dict[str, float]`, `num_datums` |
 | `OptimStepResult` | `step`, `checkpoint_id`, `sampler_path`, `state_path`, `model` |
-| `CheckpointResponse` | `id`, `name`, `is_active`, `prev_model_checkpoint_id`, `mean_reward`, `loss_fn`, `num_datums`, `num_tokens`, `metrics`, `created_at` |
+| `CheckpointResponse` | `id`, `name`, `checkpoint_name`, `is_active`, `prev_model_checkpoint_id`, `mean_reward`, `learning_rate`, `loss_fn`, `num_traces`, `num_datums`, `num_tokens`, `metrics`, `created_at` |
 
 ## `hud models` CLI
 
@@ -255,19 +198,6 @@ Under the hood `forward` returns a `ForwardResult` (`forward_id` + `data: list[D
 | `hud models checkpoints <model>` | List the checkpoint tree (active head marked). |
 | `hud models head <model> [--set <checkpoint-id>]` | Show, or set (rollback/select), the active checkpoint. |
 
-## See also
-
-<CardGroup cols={2}>
-<Card title="Designing tasks" icon="lightbulb" href="/v6/reference/advice">
-  Design tasks that produce reward spread - the prerequisite for training to work.
-</Card>
-<Card title="Tasks & Tasksets" icon="list-check" href="/v6/reference/tasks">
-  Where the rewards training learns from come from.
-</Card>
-<Card title="Run & deploy" icon="rocket" href="/v6/reference/runtime">
-  Scale the rollouts that feed the loop.
-</Card>
-<Card title="Types: Run & Trace" icon="code" href="/v6/reference/types">
-  The Run a rollout produces and the trace it carries.
-</Card>
-</CardGroup>
+For the end-to-end loop see [training agents](/v6/guides/training-agents); for the
+[`Job`](/v6/reference/types#job) and [`Run`](/v6/reference/types#run) the trainer consumes see
+[types](/v6/reference/types), and for where rollouts run see [runtimes](/v6/reference/runtime).
diff --git a/docs/v6/reference/types.mdx b/docs/v6/reference/types.mdx
index 66c7f9d0..9b30ed58 100644
--- a/docs/v6/reference/types.mdx
+++ b/docs/v6/reference/types.mdx
@@ -7,7 +7,7 @@ icon: "code"
 The serializable shapes agents, tasks, and graders exchange.
 
 ```python
-from hud import Grade, Run, Trace
+from hud import Grade, Job, Run, Trace
 from hud.types import Step
 from hud.agents.types import AgentStep, Citation, SubagentStep, ToolStep
 from hud.environment import Answer
@@ -29,6 +29,7 @@ The live handle for one task - the lifecycle plus the agent's `Trace`. You get t
 | `run.evaluation` | `dict` | The raw grade payload (`grade.raw`). |
 | `run.runtime` | `str \| None` | Control-channel url the run executed against (the placement record). |
 | `run.trace_id` | `str \| None` | Keys the trajectory for training. |
+| `run.slug` | `str \| None` | The task slug this run came from, set by the runner; how [`Job.results`](#job) keys runs back to their task without positional zip. |
 | `run.job_id` / `run.group_id` | `str \| None` | Batch + GRPO group, set by the runner. |
 
 A rollout that fails before its session is live comes back as a synthesized failed run (no prompt, no
@@ -49,6 +50,31 @@ Structured result from grading one run, parsed from the wire grade frame
 | `is_error` | `bool` | Whether grading failed. |
 | `raw` | `dict` | The full original frame. |
 
+## `Job`
+
+The receipt for one execution: the graded [`Run`](#run)s of a batch under one platform job id. Every
+run reports under a job, so even a single `task.run` returns a job of one. You get one back from
+[`task.run` / `taskset.run`](/v6/reference/tasks#running).
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `id` | `str` | Platform job id. |
+| `name` | `str` | Display name. |
+| `runs` | `list[Run]` | The graded runs, in expansion order (task-major, then group). |
+| `group` | `int` | Rollouts per task. |
+| `taskset_id` | `str \| None` | Platform taskset id when the job runs a synced taskset (`Taskset.from_api`), else `None`. |
+| `reward` | `float` | Property: mean reward across runs (`0.0` for an empty job). |
+| `results` | `dict[str, list[Run]]` | Property: runs grouped by task slug - the alignment-safe alternative to `zip(tasks, runs)`, list-valued since `group > 1` gives several runs per task. |
+
+```python
+job = await ts.run(agent, runtime=LocalRuntime("env.py"), group=4)
+print(job.reward)   # mean across every run
+```
+
+Each `run` call mints its own job by default. To gather many calls under one id - a training session, a
+multi-turn chat - open one with `Job.start(name, *, group=1, taskset_id=None)` and pass it as `job=`;
+the [training agents](/v6/guides/training-agents) guide uses this session pattern.
+
 ## `Trace`
 
 The agent's trajectory for one rollout - an ordered collection of `Step`s plus the run summary, and the
@@ -112,9 +138,5 @@ agent submits them as part of the answer.
 Declare `input=` / `returns=` on `@env.template` to surface JSON schemas in the manifest and parse the
 agent's answer into a typed `Answer[T]`. Any Pydantic model or standard type works.
 
-## See also
-
-<CardGroup cols={2}>
-<Card title="Tasks & Tasksets" icon="list-check" href="/v6/reference/tasks" />
-<Card title="Graders" icon="scale-balanced" href="/v6/reference/graders" />
-</CardGroup>
+These shapes flow through a [task](/v6/reference/tasks) run; the scores they carry come from the
+[graders](/v6/reference/graders).

From b76384a266015500e03bdfece3df347afd1503e5 Mon Sep 17 00:00:00 2001
From: lukass16 <lukasskellijs@gmail.com>
Date: Wed, 24 Jun 2026 21:18:33 -0700
Subject: [PATCH 13/16] docs(v6): expand creating-an-environment guide

Add an on-this-page directory, an export-to-other-formats section linking Harbor,
and a see-environment-examples section pointing to hud init and the cookbooks.
Fix the trailing eval-guide link and update environment cross-links to the new
reference anchors.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/v6/guides/creating-an-environment.mdx | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/docs/v6/guides/creating-an-environment.mdx b/docs/v6/guides/creating-an-environment.mdx
index fa35e19f..317cea8e 100644
--- a/docs/v6/guides/creating-an-environment.mdx
+++ b/docs/v6/guides/creating-an-environment.mdx
@@ -9,6 +9,8 @@ mode: "wide"
 This guide outlines how to create an environment in the HUD format - defining the `env.py` file, registering tasks
 and capabilities, doing quick local tests, and deploying the environment to our platform.
 
+On this page: [Start](#start) · [The `env.py` file](#the-envpy-file) · [Capabilities](#capabilities) · [Lifecycle hooks](#lifecycle-hooks) · [Tasks](#tasks) · [Testing locally](#testing-the-environment-locally) · [Deploying](#deploying-to-the-platform)
+
 ## Start
 
 Run `hud init` in your terminal. This lets you select a template to start with, the default is a blank template.
@@ -172,7 +174,7 @@ any connection, so by the time an agent connects, everything it needs is already
 hook runs, so you can write straight into `ROOT`.
 
 Hooks run per environment, not per task, so use them for state every task shares. The [environment
-reference](/v6/reference/environment#lifecycle-hooks-set-up-and-tear-down) covers the full lifecycle.
+reference](/v6/reference/environment#methods) covers the full lifecycle.
 
 <div className="guide-row">
 <div className="guide-main">
@@ -295,4 +297,14 @@ hud sync env              # sync environment metadata
 
 Your environment now lives on the platform, ready to run at scale and compare across models. Running
 those evaluations - locally, on a cloud sandbox, or on the platform - is covered in
-[](/v6/guides/running-an-eval).
+[evaluating agents](/v6/guides/running-an-eval).
+
+## Export to other formats
+
+A HUD environment isn't locked to HUD: its tasks export to other benchmark formats, like self-contained
+[Harbor](/v6/advanced/harbor-convert) task folders.
+
+## See environment examples
+
+For more to build on, pick a different starting point with `hud init`, or read the
+[cookbooks](/v6/cookbooks/index) for worked environments like a coding agent and an ops diagnostics task.

From cf5ed5a8dd63896a66936258952544d7c1997288 Mon Sep 17 00:00:00 2001
From: lukass16 <lukasskellijs@gmail.com>
Date: Wed, 24 Jun 2026 21:18:49 -0700
Subject: [PATCH 14/16] docs(v6): refine start section

Restore the HUD intro on the introduction page and restructure reading-the-docs
around Guides and Reference, pointing cookbooks at its index. Tighten the
overview wording and fix the Job anchor, and keep the overview step pills on one
line with a mermaid label overflow rule.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/custom.css            | 10 ++++++++++
 docs/v6/start/index.mdx    | 13 ++++++++++---
 docs/v6/start/overview.mdx |  6 +++---
 3 files changed, 23 insertions(+), 6 deletions(-)

diff --git a/docs/custom.css b/docs/custom.css
index 929c4772..7d23ba8b 100644
--- a/docs/custom.css
+++ b/docs/custom.css
@@ -484,6 +484,16 @@ div:has(> ul.sidebar-group > li[data-group-tag]) > .sidebar-group-header {
 #content .mermaid text {
   font-family: "trebuchet ms", verdana, arial, sans-serif !important;
 }
+/* Overview step pills stay on one line (non-breaking spaces). Any tiny
+   measure-vs-render slack on the longest pill ("Declare your environment")
+   would clip the last letters — let the label spill into the pill's internal
+   padding instead of being cut at the box edge. */
+#content .mermaid .node.clickable .nodeLabel,
+#content .mermaid .node.clickable foreignObject,
+#content .mermaid .node.clickable foreignObject > div {
+  overflow: visible !important;
+  white-space: nowrap !important;
+}
 /* Nodes with a mermaid `click` link: a subtle, minimalist hover cue — a slight
    scale-up from the node's own center, nothing imposing. */
 #content .mermaid .node.clickable {
diff --git a/docs/v6/start/index.mdx b/docs/v6/start/index.mdx
index 72bfb20a..446490a9 100644
--- a/docs/v6/start/index.mdx
+++ b/docs/v6/start/index.mdx
@@ -39,7 +39,7 @@ flowchart LR
     end
 
     AG <-->|capabilities| EN
-    EN -->|humans measure| EV["<b>evaluation</b>#160;and#160;<b>benchmarking</b>"]
+    EN -->|humans measure| EV["<b>evaluation</b> and<br/><b>benchmarking</b>"]
     EN -->|agent improves| TR["<b>training</b>"]
 
     classDef node fill:#efece8,stroke:#2b2722,stroke-width:1px,color:#2b2722;
@@ -53,13 +53,20 @@ flowchart LR
 ```
 
 
+## HUD
+
+[HUD](https://hud.ai) is a platform for building environments. You define an environment, write tasks for
+that environment, and run any agent to perform those tasks, at any scale. Our SDK is an
+[open-source](https://github.com/hud-evals/hud-python) Python framework for all of this.
+
 ## Reading the docs
 
 - [**Quickstart**](/v6/start/quickstart) - install HUD and run your first graded task in minutes.
 - [**Overview**](/v6/start/overview) - the big picture of what HUD is and how the whole workflow fits together.
-- [**Core**](/v6/reference/environment) - the heart of the docs: environments, tasks, agents, running, training, and more, each with a hands-on guide and its API.
+- [**Guides**](/v6/guides/creating-an-environment) - high-level, dedicated guides for each stage: creating environments, running evals, and training agents.
+- [**Reference**](/v6/reference/environment) - the API for each core object: environments, tasks, agents, graders, and more.
 - [**Advanced**](/v6/advanced/extending) - off the beaten path: bring your own harness, composing environments, subagents, and chat.
-- [**Cookbooks**](/v6/cookbooks/coding-agent) - worked examples and creative ways to use HUD.
+- [**Cookbooks**](/v6/cookbooks/index) - worked examples and creative ways to use HUD.
 - [**More**](/v6/more/faq) - FAQ, migrating to v6, and contributing.
 
 {/* <CardGroup cols={2}>
diff --git a/docs/v6/start/overview.mdx b/docs/v6/start/overview.mdx
index 0f0ac2f9..139b7ac7 100644
--- a/docs/v6/start/overview.mdx
+++ b/docs/v6/start/overview.mdx
@@ -12,7 +12,7 @@ specific guides on the main uses see Guides. The workflow can be split into 5 st
 ```mermaid
 %%{init: {'flowchart': {'padding': 22}}}%%
 flowchart LR
-    A(["1#160;·#160;Declare#160;your#160;environment"]) --> B(["2#160;·#160;Choose#160;your#160;taskset"]) --> C(["3#160;·#160;Choose#160;your#160;runtime"]) --> D(["4#160;·#160;Run#160;your#160;agent"]) --> E(["5#160;·#160;Learn"])
+    A(["1#160;·#160;Declare#160;environment"]) --> B(["2#160;·#160;Choose#160;your#160;taskset"]) --> C(["3#160;·#160;Choose#160;your#160;runtime"]) --> D(["4#160;·#160;Run#160;your#160;agent"]) --> E(["5#160;·#160;Learn"])
     classDef s1 fill:#efece8,stroke:#2b2722,stroke-width:1px,color:#2b2722;
     classDef s2 fill:#efece8,stroke:#2b2722,stroke-width:1px,color:#2b2722;
     classDef s3 fill:#efece8,stroke:#2b2722,stroke-width:1px,color:#2b2722;
@@ -32,7 +32,7 @@ flowchart LR
 
 ## 1 · Declare your environment
 
-In HUD any workflow starts either by creating your own environment or choosing an existing one.
+In HUD any workflow starts with creating an environment.
 
 An environment is some closed container for your agent to act in. Fundamentally it's defined by:
 
@@ -191,7 +191,7 @@ run is traced on the [platform](https://hud.ai), so you can see exactly what the
 | [**Agent**](/v6/reference/agents) | A model paired with a harness that drives it - plugged into an environment's capabilities to attempt tasks and be graded. |
 | [**Run**](/v6/reference/types#run) | A single rollout - one agent attempting one task - that produces a reward. |
 | [**Trace**](/v6/reference/types#trace) | The full, replayable timeline of a run: every action, observation, and grade. |
-| [**Job**](/v6/reference/tasks#jobs) | A collection of runs grouped together - e.g. a whole taskset evaluated by an agent. |
+| [**Job**](/v6/reference/types#job) | A collection of runs grouped together - e.g. a whole taskset evaluated by an agent. |
 
 <Accordion title="Part 4: Run your agent">
 

From 204a7ac0cfc5d11c30f94c8480d5ce50d7e6be46 Mon Sep 17 00:00:00 2001
From: lukass16 <lukasskellijs@gmail.com>
Date: Wed, 24 Jun 2026 21:22:13 -0700
Subject: [PATCH 15/16] docs(v6): fix LocalRuntime import in runtime reference

Import LocalRuntime from the public `hud` package rather than `hud.eval`.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 docs/v6/reference/runtime.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/v6/reference/runtime.mdx b/docs/v6/reference/runtime.mdx
index 1a20ec4c..1663861c 100644
--- a/docs/v6/reference/runtime.mdx
+++ b/docs/v6/reference/runtime.mdx
@@ -9,7 +9,7 @@ A **runtime** chooses where each rollout's environment runs. You pass it to `tas
 runtime changes.
 
 ```python
-from hud.eval import LocalRuntime
+from hud import LocalRuntime
 
 await taskset.run(agent, runtime=LocalRuntime("env.py"))   # serve env.py locally, run here
 ```

From f75d14258e0d926118d2bd04ae1407f2f3280b49 Mon Sep 17 00:00:00 2001
From: lukass16 <lukasskellijs@gmail.com>
Date: Wed, 24 Jun 2026 21:30:30 -0700
Subject: [PATCH 16/16] docs(readme): refresh protocol diagram and fix
 core->reference links

---
 README.md | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index a20357e8..ae9cfaeb 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@
 
 HUD is a platform for building RL environments for AI agents, across coding, browser, computer-use, and robotics. Define an environment, write tasks, and run them as evals and training across any model, at any scale.
 
-To learn more, see the [documentation](https://docs.hud.ai) and [environment reference](https://docs.hud.ai/v6/core/environment).
+To learn more, see the [documentation](https://docs.hud.ai) and [environment reference](https://docs.hud.ai/v6/reference/environment).
 
 [![PyPI](https://img.shields.io/pypi/v/hud-python?style=flat-square)](https://pypi.org/project/hud-python/)
 [![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE)
@@ -52,8 +52,9 @@ sequenceDiagram
     participant Agent
     participant Env as Environment
     participant Caps as Capabilities (ssh · mcp · cdp · rfb · robot)
-    Agent->>Env: manifest exchange
-    Env-->>Agent: capabilities + tasks
+    Note over Env,Caps: environment holds & serves these
+    Agent->>Env: hello
+    Env-->>Agent: manifest (capabilities)
     Agent->>Env: tasks.start
     Env-->>Agent: prompt
     rect rgb(238,238,238)
@@ -87,7 +88,7 @@ hud task grade fix_bug --url tcp://127.0.0.1:8765 --answer "..."
 docker rm -f run1
 ```
 
-→ [Run & deploy](https://docs.hud.ai/v6/core/runtime)
+→ [Run & deploy](https://docs.hud.ai/v6/reference/runtime)
 
 ## Environments & templates
 
@@ -114,7 +115,7 @@ hud eval tasks.py claude --group 3
 
 Each graded evaluation is a **trace** (the SDK's live handle is a `Run`). With `HUD_API_KEY` set, every rollout is recorded on [hud.ai](https://hud.ai). Tasks that need a shell, browser, GUI, or robot declare **capabilities** (below); everything else — variants, grading, batching — stays identical.
 
-→ [Quickstart](https://docs.hud.ai/v6/start/quickstart) · [Tasks & tasksets](https://docs.hud.ai/v6/core/tasks)
+→ [Quickstart](https://docs.hud.ai/v6/start/quickstart) · [Tasks & tasksets](https://docs.hud.ai/v6/reference/tasks)
 
 ## Capabilities & harnesses
 
@@ -132,13 +133,13 @@ A **capability** is a connection the environment exposes; a **harness** attaches
 
 **Bring your own:** a harness attaches to a capability and defines a tool spec — wrap `browser-use` on `cdp`, a VLA policy on `robot`, or your own agent on `ssh` / `mcp`. No protocol work required.
 
-→ [Capabilities](https://docs.hud.ai/v6/core/capabilities) · [Models](https://docs.hud.ai/v6/core/agents) · [Robots](https://docs.hud.ai/v6/advanced/robots)
+→ [Capabilities](https://docs.hud.ai/v6/reference/capabilities) · [Models](https://docs.hud.ai/v6/reference/agents) · [Robots](https://docs.hud.ai/v6/advanced/robots)
 
 ## Deploy on the platform
 
 From the [platform UI](https://hud.ai) you can run batches, compare models on the same taskset, and inspect every trace.
 
-→ [Run & deploy](https://docs.hud.ai/v6/core/runtime)
+→ [Run & deploy](https://docs.hud.ai/v6/reference/runtime)
 
 ## Train on rewards
 
@@ -161,13 +162,13 @@ await trainer.step(session.runs[start:], learning_rate=1e-5, group_size=8)
 
 HUD is the environment-and-reward source for your own GRPO/PPO loop — the same environment trains any model, text or multimodal, unchanged.
 
-→ [Training](https://docs.hud.ai/v6/core/training) · [Designing tasks for signal](https://docs.hud.ai/v6/core/advice)
+→ [Training](https://docs.hud.ai/v6/reference/training) · [Designing tasks for signal](https://docs.hud.ai/v6/reference/advice)
 
 ## Links
 
 - [Documentation](https://docs.hud.ai)
 - [Quickstart](https://docs.hud.ai/v6/start/quickstart)
-- [CLI reference](https://docs.hud.ai/v6/core/cli)
+- [CLI reference](https://docs.hud.ai/v6/reference/cli)
 - [Environment templates](https://hud.ai/environments)
 - [Supported models](https://hud.ai/models)
 - [Discord](https://discord.gg/wkjtmHYYjm)