From 34bc5541303a9723050b65b2046cd3552c7884fe Mon Sep 17 00:00:00 2001
From: enixCode <58286681+enixCode@users.noreply.github.com>
Date: Thu, 4 Jun 2026 12:15:50 +0200
Subject: [PATCH] docs(getting-started): fix the zero-to-first-workflow path

The getting-started page had several inaccuracies that would block a new user:

- Node.js requirement said >= 18; the package requires >= 20.
- Only installed light-process, never the execution server. Install both and
  explain all-in-one (auto-spawn) vs explicit-runner mode.
- The `light doctor` sample output was fictional (showed Docker checks the
  command never runs). Replaced with the real output from src/cli/doctor.ts
  for both the all-in-one and explicit-runner paths.
- Claimed a web dashboard at localhost:3000; the UI (ui/out) is not built by
  default. Added the caveat + build steps.
- Showed how to add a second node but never how to wire it. Added a `light link`
  step with --from/--to and a --when condition example.

build with cc
---
 website/content/docs/getting-started.mdx | 58 +++++++++++++++++++++---
 1 file changed, 51 insertions(+), 7 deletions(-)

diff --git a/website/content/docs/getting-started.mdx b/website/content/docs/getting-started.mdx
index 37e0e9d..7b02a58 100644
--- a/website/content/docs/getting-started.mdx
+++ b/website/content/docs/getting-started.mdx
@@ -4,29 +4,48 @@ title: "Getting Started"
 
 ## Requirements
 
-- **Node.js** >= 18 ([download](https://nodejs.org))
+- **Node.js** >= 20 ([download](https://nodejs.org))
 - **Docker** with daemon running ([download](https://docs.docker.com/get-docker/))
 
 ## Install
 
+Install both the orchestrator and the execution server:
+
 ```bash
-npm install -g light-process
+npm install -g light-process @enixcode/light-run
 ```
 
+`light-process` delegates container execution to `light-run`. Two usage modes:
+
+- **All-in-one (default):** leave `LIGHT_RUN_URL` unset. `light serve` and `light run` auto-spawn a local `light-run` process on a free port (requires the binary above).
+- **Explicit runner:** start `light-run serve` yourself, then point `LIGHT_RUN_URL` at it. Useful when the runner lives on a separate host or you want to share it across terminals.
+
 Verify your environment:
 
 ```bash
 light doctor
 ```
 
-Expected output:
+Expected output when `LIGHT_RUN_URL` is unset (all-in-one mode):
+
+```
+Checking environment...
+
+  [ok] Node.js: v20.x.x
+  [warn] LIGHT_RUN_URL: not set (all-in-one mode)
+  [ok] light-run binary: found - `light serve` will start it automatically
+
+[ok] Ready (all-in-one)
+```
+
+When `LIGHT_RUN_URL` is set and the runner is reachable:
 
 ```
 Checking environment...
 
   [ok] Node.js: v20.x.x
-  [ok] Docker: Docker version 24.x.x
-  [ok] Docker daemon: running
+  [ok] LIGHT_RUN_URL: http://localhost:3001
+  [ok] light-run /health: reachable
 
 [ok] Ready
 ```
@@ -107,13 +126,19 @@ light describe example
 
 Outputs a text tree and generates `describe.html` with an interactive Mermaid diagram.
 
-## Start the dashboard
+## Start the server
 
 ```bash
 light serve --port 3000
 ```
 
-Open `http://localhost:3000` to see the web dashboard with your workflow DAG.
+This starts the REST API server. The web dashboard (`ui/out/`) is **not built by default** - if it is absent, `GET /` returns 404 and a warning is printed at startup. To build the UI:
+
+```bash
+cd ui && npm install && npm run build
+```
+
+Once built, open `http://localhost:3000` to see the web dashboard.
 
 ## Add a new node
 
@@ -124,6 +149,25 @@ light init --node ./transform
 
 This creates a `transform/` folder with `.node.json`, `index.js`, `lp.js`, and auto-registers it in `workflow.json`.
 
+Wire it to the existing `hello` node so output flows from one to the other:
+
+```bash
+cd ..
+light link example --from hello --to transform
+```
+
+Verify the links were added:
+
+```bash
+light link example --list
+```
+
+Use `--when` to add a condition (link fires only when the condition matches):
+
+```bash
+light link example --from hello --to transform --when '{"status": "ok"}'
+```
+
 ## Add a Python node
 
 ```bash