Rebuild docs from scratch: orchestrator, delegator, and governance docs under /network

.github/workflows/docs-checks.yml

@@ -0,0 +1,21 @@
+name: Docs checks
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Structure & internal links
+        run: node scripts/check-docs.mjs
+      - name: Mintlify broken-links
+        run: |
+          npm ci
+          npx mint broken-links

.gitignore

@@ -1,8 +1,6 @@
 node_modules/
-.DS_Store
-.env
-.env.local
+.mint/
 .next/
-.mintlify/
 *.log
-.vscode/
+.DS_Store
+.playwright-mcp/

README.md

@@ -1,27 +1,67 @@
-# Livepeer Docs — `docs-v3` (clean slate)
+# Livepeer Docs
 
-This is an **orphan branch** created to experiment with a fresh docs structure
-without the historical weight of `docs-v2`. It shares no commit history with
-`main` or `docs-v2`.
+The [Mintlify](https://mintlify.com) documentation site for the Livepeer network.
 
-## Why this exists
+The current **Network** section covers running the network:
 
-`docs-v2` grew complex. `docs-v3` is a sandbox for the docs writer to try a
-new information architecture from scratch, while remaining in the same repo
-so Mintlify's per-repo billing applies once.
+- **Orchestrators** — GPU operators who run `go-livepeer` and earn ETH fees + LPT rewards.
+- **Delegators** — LPT holders who bond their stake to an orchestrator and share in its rewards.
 
-## Local preview
+A demand-side (developer) section is planned — the structure below is set up for it.
 
-```bash
-mintlify dev --port 3333
+## URL structure — `/network`
+
+Network docs live under the **`/network`** path (`docs.livepeer.org/network`). The `/network`
+prefix comes from the [`network/`](./network) folder structure, **not** from any navigation chrome —
+so the URLs are stable independent of how the sidebar/tabs are configured.
+
+This namespacing is intentional and forward-looking: a future demand-side (developer) docs section
+can be added — e.g. `/build` or `/developers` — without moving or breaking any `/network` URL. At
+that point a top-level **tab switcher** (`navigation.tabs`) gets introduced to flip between the two
+sections. Until then there's no tab, since a lone "Network" tab would be redundant chrome. The root
+(`/`) currently redirects to `/network` (see [`redirects` in `docs.json`](./docs.json)); when the
+demand-side docs ship, the root and switcher are a config change, not a URL migration.
+
+```
+/                       → redirects to /network (temporary)
+/network/*              → run the network: orchestrators + delegators
+/build/* (future)       → build on the network: developers
 ```
 
-Do not use port `3000` — it is reserved per repo policy.
+## How it's organized — Diátaxis
+
+Within each section, the sidebar follows the [Diátaxis](https://diataxis.fr) framework. Each group
+serves one need:
 
-## Returning to `docs-v2`
+| Section | Need it serves | Example |
+| --- | --- | --- |
+| **Tutorials** | Learning by doing | _Run your first orchestrator_ |
+| **How-to guides** | Achieving a specific task | _Set competitive pricing_ |
+| **Explanation** | Understanding the why | _How the network works_ |
+| **Reference** | Looking up exact facts | _CLI flags_, _Protocol parameters_ |
+
+## Run it locally
 
 ```bash
-git checkout docs-v2
+# Install the Mintlify CLI (one-time)
+npm install
+
+# Start the dev server at http://localhost:3000
+npm run dev
 ```
 
-The two branches are independent; switching is safe.
+> Requires Node.js 19+. The CLI is published as the `mint` package; `npx mint dev` also works without installing.
+
+## Edit content
+
+Every page is an `.mdx` file under [`network/`](./network). The sidebar, tabs, theme, and redirects
+live in [`docs.json`](./docs.json).
+
+## Source & accuracy
+
+Content is rebuilt from first principles based on the Livepeer v2 docs at
+<https://docs.livepeer.org>. Network values (inflation, unbonding period, active-set size,
+contract addresses) are governance-controlled and change over time — the Reference pages carry a
+"last verified" date from on-chain reads, and you can always re-verify against the
+[Livepeer Explorer](https://explorer.livepeer.org) and on-chain state. Run `npm run check` to
+validate navigation and internal links (also enforced in CI).

docs.json

@@ -1,34 +1,97 @@
 {
   "$schema": "https://mintlify.com/docs.json",
-  "theme": "palm",
+  "theme": "mint",
   "name": "Livepeer Docs",
+  "description": "Run a Livepeer orchestrator or delegate LPT. A focused guide for the supply side of the Livepeer network.",
   "colors": {
-    "primary": "#3CB540",
-    "light": "#2b9a66",
-    "dark": "#3CB540"
+    "primary": "#18794E",
+    "light": "#40BF86",
+    "dark": "#115C3B"
+  },
+  "favicon": "/favicon.svg",
+  "logo": {
+    "light": "/logo/light.svg",
+    "dark": "/logo/dark.svg"
   },
-  "favicon": "/snippets/assets/favicon.png",
   "navigation": {
-    "tabs": [
+    "groups": [
+      {
+        "group": "Get started",
+        "icon": "compass",
+        "pages": [
+          "network/index",
+          "network/who-this-is-for"
+        ]
+      },
       {
-        "tab": "Documentation",
-        "groups": [
-          {
-            "group": "Get Started",
-            "pages": ["index", "quickstart"]
-          }
+        "group": "Tutorials",
+        "icon": "graduation-cap",
+        "pages": [
+          "network/tutorials/run-your-first-orchestrator",
+          "network/tutorials/delegate-your-first-lpt"
+        ]
+      },
+      {
+        "group": "How-to guides",
+        "icon": "list-check",
+        "pages": [
+          "network/guides/orchestrator-configure",
+          "network/guides/orchestrator-activate",
+          "network/guides/orchestrator-add-ai",
+          "network/guides/orchestrator-realtime-ai",
+          "network/guides/orchestrator-pricing",
+          "network/guides/orchestrator-monitor",
+          "network/guides/delegator-acquire-lpt",
+          "network/guides/delegator-choose-orchestrator",
+          "network/guides/delegator-manage",
+          "network/guides/vote-on-a-proposal",
+          "network/guides/submit-a-protocol-lip",
+          "network/guides/submit-a-treasury-proposal"
+        ]
+      },
+      {
+        "group": "Explanation",
+        "icon": "book-open",
+        "pages": [
+          "network/explanation/orchestrators",
+          "network/explanation/delegators",
+          "network/explanation/how-the-network-works",
+          "network/explanation/economics",
+          "network/explanation/governance"
+        ]
+      },
+      {
+        "group": "Reference",
+        "icon": "square-terminal",
+        "pages": [
+          "network/reference/hardware",
+          "network/reference/cli-flags",
+          "network/reference/protocol-parameters",
+          "network/reference/contracts",
+          "network/reference/faq",
+          "network/reference/glossary"
         ]
       }
     ]
   },
-  "logo": {
-    "light": "/snippets/assets/favicon.png",
-    "dark": "/snippets/assets/favicon.png"
+  "redirects": [
+    {
+      "source": "/",
+      "destination": "/network"
+    }
+  ],
+  "navbar": {
+    "primary": {
+      "type": "button",
+      "label": "Explorer",
+      "href": "https://explorer.livepeer.org"
+    }
   },
   "footer": {
     "socials": {
       "github": "https://github.com/livepeer",
-      "x": "https://twitter.com/livepeer"
+      "discord": "https://discord.gg/livepeer",
+      "x": "https://x.com/livepeer"
     }
   }
 }

network/explanation/delegators.mdx

@@ -0,0 +1,81 @@
+---
+title: "What a delegator is"
+description: "Bonding LPT is stake attribution, not custody transfer. What delegation means, what you earn, and what you actually risk."
+---
+
+A **delegator** is an LPT holder who **bonds** their tokens to an orchestrator. This puts your
+capital to work securing the network and earning a share of that orchestrator's rewards — without
+running any hardware yourself.
+
+The single most important idea:
+
+<Tip>
+  **Delegation is stake attribution, not custody transfer.** When you bond, your LPT sits in the
+  protocol's `BondingManager` contract on Arbitrum One. The orchestrator **cannot move or spend
+  your tokens.** Your wallet is always the only party that can unbond, withdraw, or redelegate.
+</Tip>
+
+What changes when you bond is *attribution*: your balance now counts toward one specific
+orchestrator's total stake, which is what determines its rank and reward share.
+
+## Why "doing nothing" costs you
+
+Livepeer mints new LPT every round and distributes it to **bonded** stake. If you hold LPT but leave
+it unbonded, you receive none of that issuance while bonded holders do. Your share of total supply
+shrinks over time. Staying unbonded is not a neutral position — it is a slow dilution.
+
+## What you earn
+
+A bonded delegator can earn two things, both filtered through the orchestrator you pick:
+
+- **LPT inflation rewards** — a share of each round's newly minted LPT, after the orchestrator keeps its `rewardCut`.
+- **ETH fees** — a share of the ETH the orchestrator earns for compute work, according to its `feeShare`.
+
+Neither is guaranteed by bonding alone. They depend on the orchestrator staying **active** and
+reliably calling `reward()` each round. See [Economics](/network/explanation/economics) for the formulas and
+a worked example.
+
+## One wallet, one orchestrator
+
+| Commitment | What it means |
+| --- | --- |
+| One orchestrator per wallet | A bonded position points to a single orchestrator at a time. To split, use separate wallets. |
+| Arbitrum One only | Delegation happens on Arbitrum One, not Ethereum mainnet. |
+| Exit delay | Full withdrawal requires unbonding and waiting out the [unbonding period](/network/reference/protocol-parameters). |
+| Ongoing attention | Commission terms and reliability can change; check periodically. |
+
+## Switching vs exiting
+
+There are two different ways to change your position — pick by **what your problem is**:
+
+- **Redelegate** — move your stake to a different orchestrator *without* the unbonding wait. Use this when the issue is the **operator** (missed rewards, worse terms, dropped out of the active set).
+- **Unbond and withdraw** — stop participating and wait out the unbonding period before tokens return to your wallet. Use this when you want **liquid tokens** back.
+
+## What you're actually risking
+
+Slashing is **not currently active** on Livepeer mainnet, and your tokens are in the protocol
+contract — not the operator's wallet. So the real risks are operational, not custodial:
+
+- choosing an orchestrator that **misses reward calls** (the pool simply forgoes that round's inflation — there is no catch-up)
+- an operator that later changes commission terms unfavorably
+- needing liquidity before the unbonding period has passed
+- contributing to stake concentration by always picking already-dominant operators
+
+This is why **reward-call reliability matters more than a slightly better headline commission.**
+
+## Next
+
+<CardGroup cols={2}>
+  <Card title="Economics" icon="coins" href="/network/explanation/economics">
+    How rewardCut, feeShare, and inflation turn into real returns.
+  </Card>
+  <Card title="Choose an orchestrator" icon="list-check" href="/network/guides/delegator-choose-orchestrator">
+    The checklist for picking a good operator.
+  </Card>
+  <Card title="Delegate your first LPT" icon="hand-holding-dollar" href="/network/tutorials/delegate-your-first-lpt">
+    The end-to-end wallet walkthrough.
+  </Card>
+  <Card title="Protocol parameters" icon="sliders" href="/network/reference/protocol-parameters">
+    The live unbonding period and other governance values.
+  </Card>
+</CardGroup>