Publish the documentation site: docs.fluksio.com

A zensical site under docs/, served by a new `docs` compose service behind
Traefik, built with --strict in CI. Same pattern the sibling n3xd workspace
uses.

Getting started splits the way the landing page does — one path is
`pip install fluksio` and a training script, the other is a Docker stack and
an afternoon in the browser — because the two audiences will not spend the same
amount of time. Everything after that is shared: the concepts, the web
interface (app and portal), the CLI and the API, and a reference for node types,
payload types and configuration.

The three flow guides move here from the docs submodule rather than being
copied, so there is one version of them.

Styling mirrors DESIGN-GUIDELINES.md: the app's token palette remapped onto
Material's variables in both schemes, Inter, the 16px panel radius, and the one
terracotta accent spent on the facility lane of the audience split.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M7Xv3cJEW5c8AXxn2hoojV

docs/reference/payload-types.md

@@ -0,0 +1,129 @@
+# Payload types
+
+Every port declares a `dtype`, and every value that passes through it is
+checked against that declaration.
+
+This is not decoration. It is what lets the dashboard editor offer you only the
+messages a gauge can actually draw, what lets the canvas refuse a binding before
+anything runs, and what lets a downstream node know the shape of what it is
+getting before the flow starts.
+
+Everything on the wire is JSON. That is what lets the same value pass through
+the state backend, the work queue and the worker protocol unchanged.
+
+## The scalars
+
+| `dtype` | Accepts |
+|---|---|
+| `float` | any number — `int` or `float`, but not `bool` |
+| `int` | a whole number, not `bool` |
+| `str` | a string |
+| `bool` | exactly `true` or `false` |
+
+`bool` is an `int` subclass in Python and deliberately not a number here: a flag
+is not a measurement, and a switch bound to a temperature is a mistake worth
+catching.
+
+## The structured ones
+
+These are *declared shapes* rather than "some JSON", which is what makes a
+widget binding checkable.
+
+### `record`
+
+Flat named scalars.
+
+```json
+{"title": "Boiler", "body": "Pressure low", "severity": "warning"}
+```
+
+Nesting is deliberately out: a record that can contain a record is a schema
+language, and the shape stops being readable from the declaration alone.
+
+Read by the **Notification** widget. It is also what an alert channel of kind
+*dashboard* writes.
+
+### `list`
+
+Ordered items of one declared shape. The port also declares `item`:
+
+| `item` | Meaning |
+|---|---|
+| unset | `record` — what the agenda and forecast widgets read |
+| `float`, `int`, `str`, `bool` | a list of scalars |
+| `json` | anything |
+
+A list of lists, or a list of series, is refused. One declared level is the
+point.
+
+### `series`
+
+Labelled lines of `(timestamp, value)` pairs — what a chart draws.
+
+```json
+{
+  "lines": [
+    {"label": "living", "points": [[1717000000, 21.4], [1717000060, 21.5]]}
+  ],
+  "range": "-24h"
+}
+```
+
+Keys beside `lines` are carried through untouched, which is how a querying
+chart puts the window and resolution it asked for on the request and reads them
+back off the answer. That is what stops an answer to a *different* question
+from overwriting the picture.
+
+`GET /runs/series/compare` answers in this shape, which is why comparing three
+training curves is a widget binding rather than a screen of its own.
+
+### `artifact`
+
+A reference to stored bytes.
+
+```json
+{"digest": "sha256:…", "size": 4194304, "media_type": "application/octet-stream", "name": "weights.pt"}
+```
+
+Binary payloads — tensors, checkpoints, images — never travel as a message. The
+bytes go to a content-addressed store and the message carries this. A
+thirty-megabyte checkpoint never sits in the state backend, and the reference
+stays valid wherever the store is reachable from, including on another machine.
+
+Node code produces one with `fluksio.save_artifact` and opens one with
+`fluksio.load_artifact`. See [Writing node code](../code/nodes.md#bytes-artifacts).
+
+### `json`
+
+Anything JSON-serializable. The escape hatch, and the right answer when a
+payload genuinely has no fixed shape.
+
+Reach for it last. A `json` port tells the canvas, the widget picker and the
+next author nothing.
+
+## What a widget will bind to
+
+| Widget | Accepts |
+|---|---|
+| Gauge, Chart, Slider, Bar | `float`, `int` |
+| Switch | `bool` |
+| Agenda, Forecast | `list` |
+| Notification | `record` |
+| Value | anything |
+| Icon | weather strings, booleans and numbers alike |
+| Clock, Text | nothing — they bind to no message |
+
+Enforced on the server as well as in the editor.
+
+## Type failures
+
+A value that does not match its port's declaration raises on the node that
+published it, naming the port and what arrived. It does not get published, and
+it does not reach anything downstream — a wrong value stopping at its source is
+much easier to diagnose than one propagating.
+
+## See also
+
+- [Flows, nodes and messages](../concepts/flows.md)
+- [Node types](node-types.md)
+- [Dashboards and panels](../interface/dashboards.md)