docs(v6): restructure docs into guides + reference and refresh the start section

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)

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;
+}

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" }