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)
diff --git a/docs/custom.css b/docs/custom.css
index 5816ccbf..7d23ba8b 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;
@@ -418,3 +439,159 @@ 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: 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 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 {
+  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;
+}
diff --git a/docs/docs.json b/docs/docs.json
index c326f21a..db492c61 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-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"] }
+              ] },
+              { "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..0bdf59d9 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#methods) 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/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 12b37832..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
@@ -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/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 ad5e7e1a..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
@@ -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..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:
 
@@ -123,5 +127,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/agents.mdx b/docs/v6/core/agents.mdx
deleted file mode 100644
index f7553f12..00000000
--- a/docs/v6/core/agents.mdx
+++ /dev/null
@@ -1,123 +0,0 @@
----
-title: "Agents"
-description: "Agents in HUD: built-in agents like Claude, OpenAI, and Gemini, the HUD gateway for routing models, and how to wire your own agent into a task run."
-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
-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
-environment, and the trace it fills.
-
-Because an environment only exposes capabilities, the agent isn't baked in - use a built-in agent for a
-standard model, or [bring your own harness](/v6/advanced/extending#bring-your-own-harness) for a custom
-loop.
-
-## Built-in agents
-
-The SDK ships one agent per major provider, reached two ways:
-
-- **`create_agent(model)`** - the preferred path. It selects the matching provider agent for a model id
-  and routes every call through the **HUD gateway**.
-- **a provider agent directly** (e.g. `ClaudeAgent(ClaudeConfig(...))`) - the same class constructed
-  yourself, for full config control or to call the provider with your own key instead of the gateway.
-
-```python
-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 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>
-
-### Provider agents
-
-Each model maps to a provider agent - the class that speaks that provider's API. Construct one directly
-to set its full config or use your own provider key:
-
-```python
-from hud.agents import ClaudeAgent
-from hud.agents.types import ClaudeConfig
-
-agent = ClaudeAgent(ClaudeConfig(model="claude-sonnet-4-5", max_steps=30))
-```
-
-| Agent | Config | Default model |
-|-------|--------|---------------|
-| `ClaudeAgent` | `ClaudeConfig` | `claude-sonnet-4-6` |
-| `OpenAIAgent` | `OpenAIConfig` | `gpt-5.5` |
-| `GeminiAgent` | `GeminiConfig` | `gemini-3-pro-preview` |
-| `OpenAIChatAgent` | `OpenAIChatConfig` | `gpt-5.4-mini` |
-| `ClaudeSDKAgent` | `ClaudeSDKConfig` | `claude-sonnet-4-6` |
-
-Each config lives in `hud.agents.types`. `OpenAIChatAgent` speaks the OpenAI Chat Completions API, so it
-points at any compatible server (vLLM, a local model) via `base_url`; `ClaudeSDKAgent` runs the `claude`
-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
-
-Run a task with an agent two ways.
-
-**Programmatically** - pass the agent to `task.run` / `taskset.run` with a [runtime](/v6/core/runtime):
-
-```python
-from hud.agents import create_agent
-from hud.eval import LocalRuntime
-from tasks import TASKS
-
-agent = create_agent("claude-sonnet-4-5")
-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
-`.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/core/cli#hud-eval) for the full flag set and key
-resolution.
-
-## Bring your own harness
-
-Any loop or framework can be an agent: subclass `Agent`, drive the environment off the `run`, and write
-the final answer to `run.trace.content` (what gets graded). Since this is outside the standard workflow,
-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/core/capabilities" />
-<Card title="Types: Run & Trace" icon="code" href="/v6/core/types" />
-<Card title="Robots (beta)" icon="robot" href="/v6/advanced/robots" />
-</CardGroup>
diff --git a/docs/v6/core/capabilities.mdx b/docs/v6/core/capabilities.mdx
deleted file mode 100644
index f0b8a047..00000000
--- a/docs/v6/core/capabilities.mdx
+++ /dev/null
@@ -1,301 +0,0 @@
----
-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."
-icon: "plug"
----
-
-A **capability** is a connection the environment exposes; a harness attaches its own tools to it. The same environment serves a one-shot Q&A or a full computer-use rollout, depending on which capabilities a harness opens.
-
-| Protocol | Wire id | What it exposes | Spun up with |
-|----------|---------|-----------------|--------------|
-| `ssh`  | `ssh/2` | Shell + files (bash, SFTP) in a sandboxed workspace | `Workspace` (built in) |
-| `mcp`  | `mcp/2025-11-25` | Your own tools over the Model Context Protocol | `fastmcp` |
-| `cdp`  | `cdp/1.3` | Browser control over the Chrome DevTools Protocol | Chromium (`playwright`) |
-| `rfb`  | `rfb/3.8` | Full computer-use over VNC: screen + keyboard/mouse | `Xvfb` + `x11vnc` |
-| `robot` | `openpi/0` | Schema-driven robot observation/action loop over WebSocket *(beta)* | robot bridge |
-
-```python
-from hud.capabilities import Capability
-```
-
-## The `Capability` dataclass
-
-A capability is `(name, protocol, url, params)` - concrete wire data carrying the real address of something serving the protocol.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `str` | Capability name (e.g. `"shell"`, `"browser"`). |
-| `protocol` | `str` | Wire protocol id (e.g. `"ssh/2"`). |
-| `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.
-
-## 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:
-
-```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
-```
-
-**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 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>.
-
-### `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
-```
-
-<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
-
-env = Environment(name="coder")
-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()
-```
-
-### `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:
-
-```python env.py
-import asyncio
-
-from fastmcp import FastMCP
-
-from hud.capabilities import Capability
-from hud.environment import Environment
-
-server = FastMCP(name="tools")
-
-@server.tool
-def add(a: int, b: int) -> int:
-    """Add two integers."""
-    return a + b
-
-env = Environment(name="calc")
-_task: asyncio.Task | None = None
-
-@env.initialize
-async def _up():
-    global _task
-    if _task is None:                          # idempotent
-        _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
-    env.add_capability(Capability.mcp(name="tools", url="http://127.0.0.1:8040/mcp"))
-
-@env.shutdown
-async def _down():
-    global _task
-    if _task is not None:
-        _task.cancel()
-        _task = None
-```
-
-`Capability.mcp` accepts `ws`/`wss`/`http`/`https` URLs (no stdio) and an optional `auth_token=`.
-
-### `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`:
-
-```python env.py
-import asyncio
-import tempfile
-
-from playwright.async_api import async_playwright
-
-from hud.capabilities import Capability
-from hud.environment import Environment
-
-env = Environment(name="browser")
-_proc: asyncio.subprocess.Process | None = None
-
-@env.initialize
-async def _up():
-    global _proc
-    if _proc is None:
-        pw = await async_playwright().start()
-        _proc = await asyncio.create_subprocess_exec(
-            pw.chromium.executable_path,
-            "--headless=new",
-            "--remote-debugging-port=9222",
-            "--remote-debugging-address=127.0.0.1",
-            "--no-first-run",
-            "--user-data-dir=" + tempfile.mkdtemp(prefix="cdp_"),
-        )
-        await asyncio.sleep(1.0)               # wait until Chromium is ready
-    env.add_capability(Capability.cdp(name="browser", url="http://127.0.0.1:9222"))
-
-@env.shutdown
-async def _down():
-    global _proc
-    if _proc is not None:
-        _proc.terminate()
-        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.)
-
-### `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`):
-
-```python env.py
-import asyncio
-
-from hud.capabilities import Capability
-from hud.environment import Environment
-
-env = Environment(name="desktop")
-_procs: tuple | None = None
-
-@env.initialize
-async def _up():
-    global _procs
-    if _procs is None:
-        xvfb = await asyncio.create_subprocess_exec(
-            "Xvfb", ":0", "-screen", "0", "1280x1024x24",
-        )
-        await asyncio.sleep(0.5)               # let the X server come up first
-        vnc = await asyncio.create_subprocess_exec(
-            "x11vnc", "-display", ":0", "-rfbport", "5900",
-            "-localhost", "-forever", "-nopw",
-        )
-        await asyncio.sleep(1.0)               # wait until VNC is ready
-        _procs = (xvfb, vnc)
-    env.add_capability(Capability.rfb(name="screen", url="rfb://127.0.0.1", display=0))
-
-@env.shutdown
-async def _down():
-    global _procs
-    if _procs:
-        for p in reversed(_procs):
-            p.terminate()
-            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`.
-
-### `robot` - an observation/action loop
-
-```text
-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).
-
-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:
-
-```python
-endpoint = RobotEndpoint(MySimBridge())   # drive the sim only through the endpoint
-
-@env.initialize
-async def _up():
-    await endpoint.start()
-    env.add_capability(await endpoint.capability(contract=CONTRACT))
-```
-
-See [Robots](/v6/advanced/robots) for the bridge, the endpoint, the harness, and the contract spec.
-
-### 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:
-
-```python env.py
-env.workspace("workspace")                     # ssh plus file tracking
-env.workspace("workspace", track_files=False)  # ssh only
-```
-
-## Harness clients
-
-Spinning up a capability is the environment side. The harness side is the mirror: it **opens** a capability to get a live client it can drive. The capability clients live in `hud.capabilities`:
-
-| Client | Protocol |
-|--------|----------|
-| `SSHClient` | `ssh/2` (raw `asyncssh` connection via `.conn`) |
-| `MCPClient` | `mcp/2025-11-25` |
-| `CDPClient` | `cdp/1.3` |
-| `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.
-
-## 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.
-
-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:
-
-```python
-from hud.environment import Environment, Mount
-
-env = Environment(name="coder")
-env.workspace(
-    "/workspace",
-    network=True,
-    mounts=[Mount("ro", src="/data", dst="/data")],
-)
-```
-
-To run one outside an env, drive its lifecycle directly and publish `ws.capability()` as a concrete `ssh` capability:
-
-| 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.bwrap_available` | Whether `bwrap` isolation is active. |
-
-## 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" />
-</CardGroup>
diff --git a/docs/v6/core/environment.mdx b/docs/v6/core/environment.mdx
deleted file mode 100644
index 116a08cf..00000000
--- a/docs/v6/core/environment.mdx
+++ /dev/null
@@ -1,220 +0,0 @@
----
-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."
-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:
-
-- 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/core/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 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:
-
-```python env.py
-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/core/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()
-```
-
-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).
-
-### 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.
-
-```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
-```
-
-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
-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.
-
-`@env.template()` takes a few optional arguments:
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `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). |
-
-Grading, parameterizing at scale, and collecting tasks into tasksets are their own topic - see
-[Tasks & Tasksets](/v6/core/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):
-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/core/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
-`hud.environment.server`, the same entry point a container CMD runs
-(`python -m hud.environment.server <source>`):
-
-| 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. |
-
-```bash
-hud serve env.py     # serve locally on tcp://127.0.0.1:8765 while you iterate
-```
-
-<Note>
-A dependency that must **own the process main thread** (e.g. Isaac Sim / Omniverse) can't run under
-`hud serve`, which runs the asyncio loop on main. Run `serve(env, host, port)` on a worker thread
-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/core/capabilities">
-  Every protocol factory, its params, and how to spin it up.
-</Card>
-<Card title="Tasks & Tasksets" icon="list-check" href="/v6/core/tasks">
-  Add tasks that prompt and grade against this environment.
-</Card>
-<Card title="Runtime" icon="server" href="/v6/core/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>
diff --git a/docs/v6/core/tasks.mdx b/docs/v6/core/tasks.mdx
deleted file mode 100644
index 703a88b0..00000000
--- a/docs/v6/core/tasks.mdx
+++ /dev/null
@@ -1,281 +0,0 @@
----
-title: "Tasks & Tasksets"
-description: "What a task is, how you define one, and how a single definition becomes a whole dataset you can run, group into jobs, and sync."
-icon: "list-check"
----
-
-An [environment](/v6/core/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.
-
-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.
-
-## Defining a task
-
-A task is an async generator with exactly **two yields**. The first yield is the prompt; the generator
-pauses while the agent works; the agent's answer comes back into the generator; the second yield is the
-reward (`0.0`-`1.0`).
-
-```python tasks.py
-from hud import Environment
-
-env = Environment(name="letter-count")
-
-@env.template()
-async def count_letter(word: str = "strawberry", letter: str = "r"):
-    answer = yield f"How many '{letter}'s are in '{word}'?"   # 1st yield: the prompt
-    yield 1.0 if answer == str(word.count(letter)) else 0.0   # 2nd yield: the reward
-```
-
-This shape is deliberate. Everything the agent does - every step, tool call, and observation - happens
-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`:
-
-```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/core/types) (`.content` parsed, `.raw` the original string); without it, `answer` is
-the raw string the agent submitted.
-
-## One definition, many tasks
-
-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:
-
-```python tasks.py
-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
-
-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
-runs anywhere without an env object in-process - the prompt and reward arrive over the wire from the
-substrate that placement brings up.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `env` | `str` | Name of the environment the row belongs to. |
-| `id` | `str` | Task id registered on the environment. |
-| `args` | `dict` | Bound arguments (what the template was called with). |
-| `slug` | `str \| None` | Stable id for sync, filtering, and lookup. |
-| `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. |
-
-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:
-
-```python
-from hud import Task
-
-task = Task(env="letter-count", id="count_letter", args={"word": "strawberry"}, slug="count-straw")
-```
-
-## 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/core/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/core/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).
-
-## Tasksets
-
-A `Taskset` is a named collection of task rows. Build one in code, or load it from a source:
-
-```python
-from hud import Taskset
-
-# in code - the authoring case
-ts = Taskset("letters", [count_letter(word="strawberry"), count_letter(word="raspberry")])
-
-# from a Python source (.py file or directory) - scans it for Task / Taskset objects
-ts = Taskset.from_file("tasks.py")
-
-# from a data file (.json / .jsonl) - portable rows, no source needed
-ts = Taskset.from_file("tasks.jsonl")
-
-# from the platform - by taskset name or id (uses HUD_API_KEY)
-ts = Taskset.from_api("SheetBench-50")
-```
-
-Write rows back out with `ts.to_file("tasks.json")` (or `.jsonl`). Tasksets are also ordered
-collections:
-
-| Operation | Description |
-|-----------|-------------|
-| `len(ts)` / `iter(ts)` | Count / iterate tasks in order. |
-| `ts["slug"]` | Look up one task by slug. |
-| `ts.filter(slugs)` / `ts.exclude(slugs)` | Keep / drop matching slugs (returns a new taskset). |
-
-## 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:
-
-```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/core/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/core/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
-```
-
-## Syncing to the platform
-
-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.
-
-`hud sync tasks <name>` uploads a taskset and only what changed. In code, `diff()` shows that
-comparison as a `SyncPlan`:
-
-```python
-from hud.eval.sync import diff
-
-plan = diff(Taskset.from_file("tasks.py"), Taskset.from_api("SheetBench-50"))
-print(plan.summary())
-```
-
-| Field | Description |
-|-------|-------------|
-| `to_create` | Local tasks not present remotely. |
-| `to_update` | Local tasks whose content differs from remote. |
-| `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/core/environment">
-  Where the agent acts, and the capabilities a task grades against.
-</Card>
-<Card title="Graders" icon="check-double" href="/v6/core/graders">
-  Every grader, comparison helper, and the `combine` combiner.
-</Card>
-<Card title="Runtime" icon="server" href="/v6/core/runtime">
-  Where each task runs, chosen at execution time.
-</Card>
-<Card title="Designing tasks" icon="lightbulb" href="/v6/core/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/core/training.mdx
deleted file mode 100644
index 47607641..00000000
--- a/docs/v6/core/training.mdx
+++ /dev/null
@@ -1,273 +0,0 @@
----
-title: "Training"
-description: "Turn the rewards you already collect into an improving model: the loop, the TrainingClient API, losses, and the hud models CLI."
-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
-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 is a loop
-
-All of training is one loop repeated:
-
-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.
-
-```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/core/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/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
-`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
-
-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.
-
-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).
-
-## 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>
-
-## TrainingClient
-
-A `TrainingClient` drives managed training for one model: it accumulates gradients from rewarded
-trajectories and advances the weights behind the model's gateway slug in place. Inputs are `Run`s (sent
-inline) or `trace_id` strings (resolved server-side); the two can be mixed.
-
-```python
-TrainingClient(model, *, api_key=None, base_url=None, api_url=None)
-```
-
-| Argument | Default | Meaning |
-|----------|---------|---------|
-| `model` | - | Trainable model slug or id (the gateway string you also sample). |
-| `api_key` | `settings.api_key` | HUD API key. |
-| `base_url` | `settings.hud_rl_url` | Training (RL) service. |
-| `api_url` | `settings.hud_api_url` | Catalog API (resolves the slug -> id once). |
-
-### Methods
-
-| Method | Returns | Purpose |
-|--------|---------|---------|
-| `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`. |
-| `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. |
-| `available_losses()` | `list[str]` | Built-in `loss_fn` names this model's provider supports. |
-| `checkpoints()` | `list[CheckpointResponse]` | The checkpoint tree, each node with rewards, loss, counts, and a `metrics` blob. |
-| `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.
-
-## Inputs
-
-A training input is a recorded trajectory by id, or an inline one:
-
-```python
-TrainInput = str | TrajectoryPayload          # trace_id, or inline tokens + reward
-```
-
-The methods accept `str | Run | TrajectoryPayload`, mixed freely. A `Run` is converted automatically -
-inline `TrajectoryPayload` when it carries token-level samples (local rollout), else its `trace_id`
-(remote rollout). Build a `TrajectoryPayload` yourself when the tokens didn't come from a `Run` at all -
-e.g. an opponent move sampled inside the environment during self-play, trained with its own reward.
-
-| Type | Fields |
-|------|--------|
-| `TrajectorySample` | `prompt_token_ids`, `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.
-
-```python
-resp = await client.chat.completions.create(
-    model="arith-rl", messages=msgs, logprobs=True,
-    extra_body={"return_token_ids": True},
-)
-choice = resp.choices[0]
-sample = TrajectorySample(
-    prompt_token_ids=choice.prompt_token_ids,   # gateway-added fields
-    output_token_ids=choice.token_ids,
-    output_logprobs=[t.logprob for t in choice.logprobs.content],
-)
-```
-
-## Built-in losses
-
-`loss_fn` is an open string validated against the model's provider; discover the set with
-`await trainer.available_losses()`. `BuiltinLoss` lists the common Tinker names (each *is* a `str`):
-
-| `BuiltinLoss` | Value | Use |
-|---------------|-------|-----|
-| `CROSS_ENTROPY` | `cross_entropy` | Supervised - imitate sampled tokens. |
-| `IMPORTANCE_SAMPLING` | `importance_sampling` | On-policy PG, rollout-logprob ratio. |
-| `PPO` | `ppo` | Clipped-surrogate PG. |
-| `CISPO` | `cispo` | Clipped IS policy optimization. |
-| `DRO` | `dro` | Direct reward optimization. |
-
-`loss_fn_config` forwards provider-specific hyperparameters to the loss (e.g. `{"epsilon": 0.2}` for
-the `ppo` clip). The supported keys are provider-defined and not every loss accepts config, so prefer
-the defaults (`None`) unless a provider documents a key.
-
-## Custom losses
-
-`forward_backward_custom` runs the current-policy forward pass server-side, hands you per-token tensors,
-runs your loss locally (torch autograd), and ships the per-token gradients back. Requires torch
-(`pip install 'hud-python[train]'`).
-
-```python
-import torch
-from hud.train import DatumTensors
-
-def my_loss(data: list[DatumTensors], logprobs: list[torch.Tensor]):
-    loss = logprobs[0].new_zeros(())
-    for datum, policy_lp in zip(data, logprobs):
-        ratio = torch.exp(policy_lp - torch.tensor(datum.sampling_logprobs))
-        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)
-```
-
-`logprobs[i]` are the current policy for datum `i` as differentiable leaves. Everything else is constant
-on the matching `DatumTensors`:
-
-| `DatumTensors` | Meaning |
-|----------------|---------|
-| `logprobs` | Current-policy, per token (the differentiable leaf). |
-| `sampling_logprobs` | Rollout policy, per token. |
-| `mask` | `1.0` on action tokens, `0.0` on observation tokens. |
-| `reward`, `traj_idx`, `group_idx` | Trajectory reward, source trajectory, GRPO group (or `None`). |
-
-Under the hood `forward` returns a `ForwardResult` (`forward_id` + `data: list[DatumTensors]`);
-`backward(forward_id, weights)` applies `weights[d][t] = -dC/dlogprobs`.
-
-## Results
-
-| Type | Fields |
-|------|--------|
-| `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` |
-
-## `hud models` CLI
-
-| Command | Purpose |
-|---------|---------|
-| `hud models list` | List gateway models. |
-| `hud models fork <model> --name <slug>` | Fork a team-owned trainable model from an existing one. |
-| `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/core/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">
-  Where the rewards training learns from come from.
-</Card>
-<Card title="Run & deploy" icon="rocket" href="/v6/core/runtime">
-  Scale the rollouts that feed the loop.
-</Card>
-<Card title="Types: Run & Trace" icon="code" href="/v6/core/types">
-  The Run a rollout produces and the trace it carries.
-</Card>
-</CardGroup>
diff --git a/docs/v6/guides/creating-an-environment.mdx b/docs/v6/guides/creating-an-environment.mdx
new file mode 100644
index 00000000..317cea8e
--- /dev/null
+++ b/docs/v6/guides/creating-an-environment.mdx
@@ -0,0 +1,310 @@
+---
+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 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.
+
+```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. 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 example">
+
+We'll use the following `env.py` example in this section 
+
+```python env.py
+from pathlib import Path
+from hud.environment import Environment
+
+ROOT = Path("workspace")
+env = Environment(name="counter")
+env.workspace(ROOT)
+
+@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.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.workspace(ROOT)
+```
+
+</div>
+</div>
+
+## Capabilities
+
+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
+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"))
+```
+
+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)
+```
+
+</div>
+</div>
+
+## Lifecycle hooks
+
+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`.
+
+Hooks run per environment, not per task, so use them for state every task shares. The [environment
+reference](/v6/reference/environment#methods) covers the full lifecycle.
+
+<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="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
+```
+
+</div>
+</div>
+
+## 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
+agent's answer to the count Python computes. You have three options as tasks grow:
+
+| Approach | What it does |
+| --- | --- |
+| 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. |
+
+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`
+
+`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 count
+
+tasks = [
+    count(sentence="strawberry", letter="r"),
+    count(sentence="banana", letter="a"),
+]
+```
+
+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
+```
+
+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
+
+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).
+
+## 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.
diff --git a/docs/v6/guides/running-an-eval.mdx b/docs/v6/guides/running-an-eval.mdx
new file mode 100644
index 00000000..ad7a2187
--- /dev/null
+++ b/docs/v6/guides/running-an-eval.mdx
@@ -0,0 +1,158 @@
+---
+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"
+---
+
+
+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:
+
+| Workflow | When to use it | Where you start it |
+| --- | --- | --- |
+| [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
+
+A **deployed environment** has been built and published to the platform with
+[`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.
+
+**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
+```
+
+**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
+
+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   # a cheaper model for fast iteration
+hud eval "My Taskset" openai --model gpt-5
+hud eval "My Taskset" gemini
+```
+
+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).
+
+### 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 [platform](https://hud.ai). You can also read them
+from the terminal:
+
+```bash
+hud jobs               # recent jobs - id, name, taskset, status
+hud jobs <job-id>      # the traces in one job
+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; 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 [platform](https://hud.ai). Without one, they
+run and grade entirely on your machine with no platform calls.
+</Note>
+
+### With `hud eval`
+
+`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">
+
+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">terminal</p>
+
+```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>
+
+### 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
+is the same eval `hud eval` runs, written out in Python.
+
+```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())
+```
+
+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")` | 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 |
+
+The [runtime reference](/v6/reference/runtime) covers each constructor and how to bring your own.
+
+### Serving an environment directly
+
+`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
+```
+
+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.
+
+With runs in hand, turn the reward spread into model updates - covered in
+[training agents](/v6/guides/training-agents).
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/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/reference/agents.mdx b/docs/v6/reference/agents.mdx
new file mode 100644
index 00000000..7a8994fa
--- /dev/null
+++ b/docs/v6/reference/agents.mdx
@@ -0,0 +1,128 @@
+---
+title: "Agents"
+description: "Agents in HUD: built-in agents like Claude, OpenAI, and Gemini, the HUD gateway for routing models, and how to wire your own agent into a task run."
+icon: "robot"
+mode: "wide"
+---
+
+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
+environment, and the trace it fills.
+
+Because an environment only exposes capabilities, the agent isn't baked in - use a built-in agent for a
+standard model, or [bring your own harness](/v6/advanced/extending#bring-your-own-harness) for a custom
+loop.
+
+## Built-in agents
+
+The SDK ships one agent per major provider, reached two ways:
+
+- **`create_agent(model)`** - the preferred path. It selects the matching provider agent for a model id
+  and routes every call through the **HUD gateway**.
+- **a provider agent directly** (e.g. `ClaudeAgent(ClaudeConfig(...))`) - the same class constructed
+  yourself, for full config control or to call the provider with your own key instead of the gateway.
+
+```python
+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 (`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.
+
+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
+
+Each model maps to a provider agent - the class that speaks that provider's API. Construct one directly
+to set its full config or use your own provider key:
+
+```python
+from hud.agents import ClaudeAgent
+from hud.agents.types import ClaudeConfig
+
+agent = ClaudeAgent(ClaudeConfig(model="claude-sonnet-4-5", max_steps=30))
+```
+
+| Agent | Config | Default model |
+|-------|--------|---------------|
+| `ClaudeAgent` | `ClaudeConfig` | `claude-sonnet-4-6` |
+| `OpenAIAgent` | `OpenAIConfig` | `gpt-5.5` |
+| `GeminiAgent` | `GeminiConfig` | `gemini-3-pro-preview` |
+| `OpenAIChatAgent` | `OpenAIChatConfig` | `gpt-5.4-mini` |
+| `ClaudeSDKAgent` | `ClaudeSDKConfig` | `claude-sonnet-4-6` |
+
+Each config lives in `hud.agents.types`. `OpenAIChatAgent` speaks the OpenAI Chat Completions API, so it
+points at any compatible server (vLLM, a local model) via `base_url`; `ClaudeSDKAgent` runs the `claude`
+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.
+
+## 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`.
+
+A model id maps to one of four gateway agent types (`AgentType`), each a provider agent:
+
+| `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, Taskset
+
+agent = create_agent("claude-sonnet-4-5")
+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**, `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
+
+Any loop or framework can be an agent: subclass `Agent`, drive the environment off the `run`, and write
+the final answer to `run.trace.content` (what gets graded). Since this is outside the standard workflow,
+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).
+
+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
new file mode 100644
index 00000000..808344e7
--- /dev/null
+++ b/docs/v6/reference/capabilities.mdx
@@ -0,0 +1,322 @@
+---
+title: "Capabilities"
+description: "The wire protocols an environment exposes, each protocol's factory signature, and the clients that attach to them."
+icon: "plug"
+---
+
+A **capability** is a connection the environment exposes; a harness attaches its own tools to it. The same environment serves a one-shot Q&A or a full computer-use rollout, depending on which capabilities a harness opens.
+
+| Protocol | Wire id | What it exposes | Spun up with |
+|----------|---------|-----------------|--------------|
+| `ssh`  | `ssh/2` | Shell + files (bash, SFTP) in a sandboxed workspace | `Workspace` (built in) |
+| `mcp`  | `mcp/2025-11-25` | Your own tools over the Model Context Protocol | `fastmcp` |
+| `cdp`  | `cdp/1.3` | Browser control over the Chrome DevTools Protocol | Chromium (`playwright`) |
+| `rfb`  | `rfb/3.8` | Full computer-use over VNC: screen + keyboard/mouse | `Xvfb` + `x11vnc` |
+| `robot` | `openpi/0` | Schema-driven robot observation/action loop over WebSocket *(beta)* | robot bridge |
+
+```python
+from hud.capabilities import Capability
+```
+
+## The `Capability` dataclass
+
+A capability is `(name, protocol, url, params)` - concrete wire data carrying the real address of something serving the protocol.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `str` | Capability name (e.g. `"shell"`, `"browser"`). |
+| `protocol` | `str` | Wire protocol id (e.g. `"ssh/2"`). |
+| `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 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. 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:
+
+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`.
+
+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.
+
+## Factories
+
+### `ssh` - a sandboxed shell
+
+```text
+Capability.ssh(*, name="shell", url, user="agent", host_pubkey, client_key=None, client_key_path=None, shell=None)
+```
+
+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.
+
+| 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`. |
+
+### `mcp` - your own tools
+
+```text
+Capability.mcp(*, name="tools", url, auth_token=None)
+```
+
+| 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
+
+from fastmcp import FastMCP
+
+from hud.capabilities import Capability
+from hud.environment import Environment
+
+server = FastMCP(name="tools")
+
+@server.tool
+def add(a: int, b: int) -> int:
+    """Add two integers."""
+    return a + b
+
+env = Environment(name="calc")
+_task: asyncio.Task | None = None
+
+@env.initialize
+async def _up():
+    global _task
+    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)
+    env.add_capability(Capability.mcp(name="tools", url="http://127.0.0.1:8040/mcp"))
+
+@env.shutdown
+async def _down():
+    global _task
+    if _task is not None:
+        _task.cancel()
+        _task = None
+```
+</Accordion>
+
+### `cdp` - a browser
+
+```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
+
+from playwright.async_api import async_playwright
+
+from hud.capabilities import Capability
+from hud.environment import Environment
+
+env = Environment(name="browser")
+_proc: asyncio.subprocess.Process | None = None
+
+@env.initialize
+async def _up():
+    global _proc
+    if _proc is None:
+        pw = await async_playwright().start()
+        _proc = await asyncio.create_subprocess_exec(
+            pw.chromium.executable_path,
+            "--headless=new",
+            "--remote-debugging-port=9222",
+            "--remote-debugging-address=127.0.0.1",
+            "--no-first-run",
+            "--user-data-dir=" + tempfile.mkdtemp(prefix="cdp_"),
+        )
+        await asyncio.sleep(1.0)
+    env.add_capability(Capability.cdp(name="browser", url="http://127.0.0.1:9222"))
+
+@env.shutdown
+async def _down():
+    global _proc
+    if _proc is not None:
+        _proc.terminate()
+        await _proc.wait()
+        _proc = None
+```
+</Accordion>
+
+### `rfb` - a virtual screen
+
+```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
+
+from hud.capabilities import Capability
+from hud.environment import Environment
+
+env = Environment(name="desktop")
+_procs: tuple | None = None
+
+@env.initialize
+async def _up():
+    global _procs
+    if _procs is None:
+        xvfb = await asyncio.create_subprocess_exec(
+            "Xvfb", ":0", "-screen", "0", "1280x1024x24",
+        )
+        await asyncio.sleep(0.5)
+        vnc = await asyncio.create_subprocess_exec(
+            "x11vnc", "-display", ":0", "-rfbport", "5900",
+            "-localhost", "-forever", "-nopw",
+        )
+        await asyncio.sleep(1.0)
+        _procs = (xvfb, vnc)
+    env.add_capability(Capability.rfb(name="screen", url="rfb://127.0.0.1", display=0))
+
+@env.shutdown
+async def _down():
+    global _procs
+    if _procs:
+        for p in reversed(_procs):
+            p.terminate()
+            await p.wait()
+        _procs = None
+```
+</Accordion>
+
+### `robot` - an observation/action loop
+
+```text
+Capability.robot(*, name="robot", url, contract)
+```
+
+| 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 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
+
+@env.initialize
+async def _up():
+    await endpoint.start()
+    env.add_capability(await endpoint.capability(contract=CONTRACT))
+```
+
+See [Robots](/v6/advanced/robots) for the bridge, the endpoint, the harness, and the contract spec.
+
+## 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 (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
+env.workspace("workspace", track_files=False)  # ssh only
+```
+
+## Harness clients
+
+Spinning up a capability is the environment side. The harness side is the mirror: it **opens** a capability to get a live client it can drive. The capability clients live in `hud.capabilities`:
+
+| Client | Protocol |
+|--------|----------|
+| `SSHClient` | `ssh/2` (raw `asyncssh` connection via `.conn`) |
+| `MCPClient` | `mcp/2025-11-25` |
+| `CDPClient` | `cdp/1.3` |
+| `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/reference/agents)). To write your own harness, attach to the capability you need and define your tool spec.
+
+## 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, ...)`](/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, Workspace
+
+env = Environment(name="coder")
+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()
+```
+
+<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 |
+|--------|-------------|
+| `await ws.start()` | Start the SSH accept loop (idempotent). |
+| `await ws.stop()` | Stop accepting sessions and release the socket. |
+| `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). |
+
+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`.
+
+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/core/cli.mdx b/docs/v6/reference/cli.mdx
similarity index 89%
rename from docs/v6/core/cli.mdx
rename to docs/v6/reference/cli.mdx
index 4aa276c2..807bd9b6 100644
--- a/docs/v6/core/cli.mdx
+++ b/docs/v6/reference/cli.mdx
@@ -1,6 +1,6 @@
 ---
 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."
+description: "The hud command reference across the environment lifecycle."
 icon: "terminal"
 ---
 
@@ -10,7 +10,7 @@ Install the CLI with `uv tool install hud-python --python 3.12`. Authenticate on
 
 ### `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.
+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>
@@ -22,7 +22,7 @@ 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. |
+| `--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. |
 
@@ -178,5 +178,5 @@ rollout so `hud trace` can read them offline without an API call.
 
 <CardGroup cols={2}>
 <Card title="Quickstart" icon="bolt" href="/v6/start/quickstart" />
-<Card title="Run & deploy" icon="rocket" href="/v6/core/runtime" />
+<Card title="Run & deploy" icon="rocket" href="/v6/reference/runtime" />
 </CardGroup>
diff --git a/docs/v6/reference/environment.mdx b/docs/v6/reference/environment.mdx
new file mode 100644
index 00000000..45f35e89
--- /dev/null
+++ b/docs/v6/reference/environment.mdx
@@ -0,0 +1,88 @@
+---
+title: "Environments"
+description: "The Environment control object, its registration methods, and how to serve one over the wire protocol."
+icon: "cube"
+---
+
+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
+
+`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
+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). |
+## Methods
+
+You register capabilities, lifecycle hooks, and tasks against the object with these methods. Each
+becomes part of what the environment advertises when it serves.
+
+| 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`). |
+
+The `@env.template()` decorator takes optional arguments:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `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/reference/types). |
+
+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()`](/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 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
+```
+
+<Note>
+A dependency that must **own the process main thread** (e.g. Isaac Sim / Omniverse) can't run under
+`hud serve`, which runs the asyncio loop on main. Run `serve(env, host, port)` on a worker thread
+instead and keep the main thread for the dependency - see [Robots](/v6/advanced/robots#environment-side).
+</Note>
+
+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/core/graders.mdx b/docs/v6/reference/graders.mdx
similarity index 77%
rename from docs/v6/core/graders.mdx
rename to docs/v6/reference/graders.mdx
index 651b3793..c1da269c 100644
--- a/docs/v6/core/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/core/tasks" />
-<Card title="Designing tasks" icon="signal" href="/v6/core/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/core/runtime.mdx b/docs/v6/reference/runtime.mdx
similarity index 65%
rename from docs/v6/core/runtime.mdx
rename to docs/v6/reference/runtime.mdx
index b5acd2da..1663861c 100644
--- a/docs/v6/core/runtime.mdx
+++ b/docs/v6/reference/runtime.mdx
@@ -1,29 +1,19 @@
 ---
-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: "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
+from hud 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/core/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/core/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
new file mode 100644
index 00000000..55e871e8
--- /dev/null
+++ b/docs/v6/reference/tasks.mdx
@@ -0,0 +1,190 @@
+---
+title: "Tasks & Tasksets"
+description: "What a task is, how you define one, and how a single definition becomes a whole dataset you can run, group into jobs, and sync."
+icon: "list-check"
+---
+
+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
+
+A task is an async generator with exactly **two yields**. The first yield is the prompt; the generator
+pauses while the agent works; the agent's answer comes back into the generator; the second yield is the
+reward (`0.0`-`1.0`).
+
+```python tasks.py
+from hud import Environment
+
+env = Environment(name="letter-count")
+
+@env.template()
+async def count_letter(word: str = "strawberry", letter: str = "r"):
+    answer = yield f"How many '{letter}'s are in '{word}'?"   # 1st yield: the prompt
+    yield 1.0 if answer == str(word.count(letter)) else 0.0   # 2nd yield: the reward
+```
+
+This shape is deliberate. Everything the agent does - every step, tool call, and observation - happens
+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.
+
+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
+```
+
+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). |
+
+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.
+
+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")]
+```
+
+Parameterize across difficulties, inputs, or seeds and one definition becomes an entire benchmark.
+
+## 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
+runs anywhere without an env object in-process - the prompt and reward arrive over the wire from the
+substrate that placement brings up.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `env` | `str` | Name of the environment the row belongs to. |
+| `id` | `str` | Task id registered on the environment. |
+| `args` | `dict` | Bound arguments (what the template was called with). |
+| `slug` | `str \| None` | Stable id for sync, filtering, and lookup. |
+| `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/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:
+
+```python
+from hud import Task
+
+task = Task(env="letter-count", id="count_letter", args={"word": "strawberry"}, slug="count-straw")
+```
+
+## Grading
+
+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
+
+A `Taskset` is a named collection of task rows. Build one in code, or load it from a source:
+
+```python
+from hud import Taskset
+
+# in code - the authoring case
+ts = Taskset("letters", [count_letter(word="strawberry"), count_letter(word="raspberry")])
+
+# from a Python source (.py file or directory) - scans it for Task / Taskset objects
+ts = Taskset.from_file("tasks.py")
+
+# from a data file (.json / .jsonl) - portable rows, no source needed
+ts = Taskset.from_file("tasks.jsonl")
+
+# from the platform - by taskset name or id (uses HUD_API_KEY)
+ts = Taskset.from_api("SheetBench-50")
+```
+
+Write rows back out with `ts.to_file("tasks.json")` (or `.jsonl`). Tasksets are also ordered
+collections:
+
+| Operation | Description |
+|-----------|-------------|
+| `len(ts)` / `iter(ts)` | Count / iterate tasks in order. |
+| `ts["slug"]` | Look up one task by slug. |
+| `ts.filter(slugs)` / `ts.exclude(slugs)` | Keep / drop matching slugs (returns a new taskset). |
+
+## Running
+
+`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
+
+job = await ts.run(agent, runtime=LocalRuntime("env.py"), group=8, max_concurrent=10)
+```
+
+| 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. |
+
+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).
+
+## Syncing
+
+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
+
+plan = diff(Taskset.from_file("tasks.py"), Taskset.from_api("SheetBench-50"))
+print(plan.summary())
+```
+
+| Field | Description |
+|-------|-------------|
+| `to_create` | Local tasks not present remotely. |
+| `to_update` | Local tasks whose content differs from remote. |
+| `unchanged` | Local tasks that match remote. |
+| `remote_only` | Remote tasks with no local counterpart. |
+
+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
new file mode 100644
index 00000000..6ae60c78
--- /dev/null
+++ b/docs/v6/reference/training.mdx
@@ -0,0 +1,203 @@
+---
+title: "Training"
+description: "The TrainingClient API, training paths, losses, results, and the hud models CLI."
+icon: "dumbbell"
+mode: "wide"
+---
+
+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 paths
+
+Each path accumulates gradients differently, then applies them with the same `optim_step`. All operate on
+a [`TrainingClient`](#trainingclient) except the last.
+
+| 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 |
+
+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.
+
+## Objects
+
+| 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
+
+A `TrainingClient` drives managed training for one model: it accumulates gradients from rewarded
+trajectories and advances the weights behind the model's gateway slug in place. Inputs are `Run`s (sent
+inline) or `trace_id` strings (resolved server-side); the two can be mixed.
+
+```python
+TrainingClient(model, *, api_key=None, base_url=None, api_url=None)
+```
+
+| Argument | Default | Meaning |
+|----------|---------|---------|
+| `model` | - | Trainable model slug or id (the gateway string you also sample). |
+| `api_key` | `settings.api_key` | HUD API key. |
+| `base_url` | `settings.hud_rl_url` | Training (RL) service. |
+| `api_url` | `settings.hud_api_url` | Catalog API (resolves the slug -> id once). |
+
+### Methods
+
+| Method | Returns | Purpose |
+|--------|---------|---------|
+| `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, 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. |
+| `available_losses()` | `list[str]` | Built-in `loss_fn` names this model's provider supports. |
+| `checkpoints()` | `list[CheckpointResponse]` | The checkpoint tree, each node with rewards, loss, counts, and a `metrics` blob. |
+| `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 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
+
+A training input is a recorded trajectory by id, or an inline one:
+
+```python
+TrainInput = str | TrajectoryPayload          # trace_id, or inline tokens + reward
+```
+
+The methods accept `str | Run | TrajectoryPayload`, mixed freely. A `Run` is converted automatically -
+inline `TrajectoryPayload` when it carries token-level samples (local rollout), else its `trace_id`
+(remote rollout). Build a `TrajectoryPayload` yourself when the tokens didn't come from a `Run` at all -
+e.g. an opponent move sampled inside the environment during self-play, trained with its own reward.
+
+| Type | Fields |
+|------|--------|
+| `TrajectorySample` | `prompt_token_ids`, `prompt_chunks`, `output_token_ids`, `output_logprobs` |
+| `TrajectoryPayload` | `samples: list[TrajectorySample]`, `reward`, `trace_id=None` |
+
+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(
+    model="arith-rl", messages=msgs, logprobs=True,
+    extra_body={"return_token_ids": True},
+)
+choice = resp.choices[0]
+sample = TrajectorySample(
+    prompt_token_ids=choice.prompt_token_ids,   # gateway-added fields
+    output_token_ids=choice.token_ids,
+    output_logprobs=[t.logprob for t in choice.logprobs.content],
+)
+```
+
+## Built-in losses
+
+`loss_fn` is an open string validated against the model's provider; discover the set with
+`await trainer.available_losses()`. `BuiltinLoss` lists the common Tinker names (each *is* a `str`):
+
+| `BuiltinLoss` | Value | Use |
+|---------------|-------|-----|
+| `CROSS_ENTROPY` | `cross_entropy` | Supervised - imitate sampled tokens. |
+| `IMPORTANCE_SAMPLING` | `importance_sampling` | On-policy PG, rollout-logprob ratio. |
+| `PPO` | `ppo` | Clipped-surrogate PG. |
+| `CISPO` | `cispo` | Clipped IS policy optimization. |
+| `DRO` | `dro` | Direct reward optimization. |
+
+`loss_fn_config` forwards provider-specific hyperparameters to the loss (e.g. `{"epsilon": 0.2}` for
+the `ppo` clip). The supported keys are provider-defined and not every loss accepts config, so prefer
+the defaults (`None`) unless a provider documents a key.
+
+## Custom losses
+
+`forward_backward_custom` runs the current-policy forward pass server-side, hands you per-token tensors,
+runs your loss locally (torch autograd), and ships the per-token gradients back. Requires torch
+(`pip install 'hud-python[train]'`).
+
+```python
+import torch
+from hud.train import DatumTensors
+
+def my_loss(data: list[DatumTensors], logprobs: list[torch.Tensor]):
+    loss = logprobs[0].new_zeros(())
+    for datum, policy_lp in zip(data, logprobs):
+        ratio = torch.exp(policy_lp - torch.tensor(datum.sampling_logprobs))
+        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)   # 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`:
+
+| `DatumTensors` | Meaning |
+|----------------|---------|
+| `logprobs` | Current-policy, per token (the differentiable leaf). |
+| `sampling_logprobs` | Rollout policy, per token. |
+| `mask` | `1.0` on action tokens, `0.0` on observation tokens. |
+| `reward`, `traj_idx`, `group_idx` | Trajectory reward, source trajectory, GRPO group (or `None`). |
+
+Under the hood `forward` returns a `ForwardResult` (`forward_id` + `data: list[DatumTensors]`);
+`backward(forward_id, weights)` applies `weights[d][t] = -dC/dlogprobs`.
+
+## Results
+
+| Type | Fields |
+|------|--------|
+| `ForwardBackwardResult` | `metrics: dict[str, float]`, `num_datums` |
+| `OptimStepResult` | `step`, `checkpoint_id`, `sampler_path`, `state_path`, `model` |
+| `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
+
+| Command | Purpose |
+|---------|---------|
+| `hud models list` | List gateway models. |
+| `hud models fork <model> --name <slug>` | Fork a team-owned trainable model from an existing one. |
+| `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. |
+
+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/core/types.mdx b/docs/v6/reference/types.mdx
similarity index 74%
rename from docs/v6/core/types.mdx
rename to docs/v6/reference/types.mdx
index 1ddaa607..9b30ed58 100644
--- a/docs/v6/core/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
@@ -105,16 +131,12 @@ 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
 
 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/core/tasks" />
-<Card title="Graders" icon="scale-balanced" href="/v6/core/graders" />
-</CardGroup>
+These shapes flow through a [task](/v6/reference/tasks) run; the scores they carry come from the
+[graders](/v6/reference/graders).
diff --git a/docs/v6/start/index.mdx b/docs/v6/start/index.mdx
index d9bcdac9..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> and <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,23 +53,30 @@ 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/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.
+- [**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}>
 <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/overview.mdx b/docs/v6/start/overview.mdx
new file mode 100644
index 00000000..139b7ac7
--- /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;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 with creating an 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 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/types#job) | 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).
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>
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()