Make documentation standalone and generalize examples

README.md

@@ -1,11 +1,11 @@
 # Fluksio App
 
-Fluksio is a node-based automation software that brings trust and reliability to your flow.
-It just works and looks good.
+Connect a few nodes, give their messages names, and let Fluksio handle the
+running. Use live flows for automation and batch runs for experiments, with
+dashboards to see what happened.
 
-The core of Fluksio: a node-based, test-driven automation software built to scale. This
-repo holds the FastAPI backend, the flow engine, and the dashboard SPA, built into one
-image that serves all three on one port.
+This repository holds the FastAPI backend, flow engine and dashboard SPA.
+The Docker image serves all three on one port.
 
 ## Layout
 
@@ -23,30 +23,32 @@ scripts/        generate-client.sh, test.sh
 
 ## Install without Docker
 
-Get started quickly by running
+Start an engine with Python 3.12 or newer on Linux or macOS:
 
 ```sh
 pip install fluksio
 fluksio serve
 ```
 
-Then, head over to [fluksio.com](https://fluksio.com), sign up and add a new instance.
-Using the code provided, run
+For the optional browser portal, sign up at [fluksio.com](https://fluksio.com)
+and add an instance. Use the code it gives you:
 
 ```sh
 fluksio enroll <code>
 ```
 
-and you're ready to rock.
-
-Fluksio is distributed at it's heart.
-A machine that should only *run nodes* for an engine elsewhere installs less:
+Your engine also works without enrollment. A machine that only runs nodes
+for another engine needs just the worker package:
 
 ```sh
 pip install fluksio-worker
-FLUKSIO_WORKER_TOKEN=… fluksio-worker --url wss://api.fluksio.com/api/v1/workers/attach --labels gpu
+FLUKSIO_WORKER_TOKEN='<worker-token>' fluksio-worker \
+  --url wss://fluksio.example.com/api/v1/workers/attach --labels gpu
 ```
 
+Replace the example address with your engine's URL and create a token as
+described in [Remote workers](docs/code/workers.md).
+
 ## Getting started
 
 Needs Docker with Compose v2, on x86-64 or arm64 such as a Raspberry Pi 4 or 5.
@@ -82,7 +84,8 @@ make lint           # ruff + mypy + biome
 make generate-client  # regenerate the frontend SDK from the OpenAPI schema
 ```
 
-`make help` lists every target.
+`make help` lists every target. See [Development](development.md) for stack
+options and checks.
 
 ## Documentation
 
@@ -96,7 +99,6 @@ make docs         # static build into ./site
 It is served at `docs.${DOMAIN}` by the `docs` service in `docker/compose.yml`,
 and `.gitea/workflows/docs.yml` builds it with `--strict` on every push.
 
-
 ## License
 
 Copyright (C) 2026 Melvin Strobl - GNU Affero General Public License v3.0 or