Make the docs state things rather than argue them
Docs / docs (push) Successful in 37s
Playwright Tests / test-playwright (1, 2) (push) Failing after 1m35s
Playwright Tests / test-playwright (2, 2) (push) Failing after 17s
pre-commit / pre-commit (push) Failing after 2m8s
Test Backend / test-backend (push) Failing after 2m48s
Compose Smoke Test / test-compose (push) Failing after 13s
Playwright Tests / merge-reports (push) Failing after 2m25s

The site read as a design journal: rationale paragraphs, hedges
("deliberately", "on purpose", "genuinely"), meta-commentary about the docs
themselves, and one em-dash every ten lines carrying an aside.

Roughly twenty rationale blocks are gone or reduced to what a reader needs
in order to use the thing. Em-dashes go from 507 to 135, and what is left is
structural rather than prose: list and definition separators, table cells,
and four inside code blocks that quote what the CLI actually prints.

Also: api.example.com becomes api.fluksio.com (the emails stay, since
bootstrap.py really defaults to admin@example.com and RFC 2606 reserves it);
the mqtt table gains the two settings it had drifted behind on and inject's
wording matches the engine; llms.txt lists the two connector pages that were
in the nav but not in it; and the two device/device_policy notes now agree.

Builds clean under `zensical build --strict`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015YrQnKV3bnQd4K342y8tKj
This commit is contained in:
2026-08-31 10:49:58 +02:00
co-authored by Claude Opus 5
parent 2422a9b22b
commit bdad6d7fc2
25 changed files with 450 additions and 479 deletions
+12 -14
View File
@@ -5,14 +5,12 @@ full-bleed graph, so what you are looking at is always the flow.
## The canvas
Nodes are laid out for you left to right on a desktop, top to bottom on a
phone and the arrangement is recomputed as the graph changes. There is
Nodes are laid out for you, left to right on a desktop and top to bottom on a
phone, and the arrangement is recomputed as the graph changes. There is
nothing to drag and nothing to tidy.
That is on purpose. The edges come from message names, so a stored layout would
be a second, weaker description of the same thing, and something to merge when
two people edit the same flow. It also keeps flows honest: a graph nobody can
hand-arrange is one worth splitting.
The edges come from message names, so there is no layout to store or to merge
when two people edit the same flow.
What is drawn:
@@ -38,7 +36,7 @@ the canvas with its panel open.
Floats on the right; a full-screen sheet on a phone.
**Consumes** and **Provides** are the ports. Each row is a message name, a
payload type, and on an output a *streaming* toggle for ports that publish
payload type, and, on an output, a *streaming* toggle for ports that publish
repeatedly during one execution. The name field suggests messages already in
the flow, which is usually how you wire something: type the name that already
exists.
@@ -47,7 +45,7 @@ Renaming an output renames the message everywhere it is read. Inputs are not
renamed, because an input is more often re-pointed at a different message than
renamed.
**Settings** is generated from the node type's parameter schema so an MQTT
**Settings** is generated from the node type's parameter schema, so an MQTT
node shows broker, topic and QoS, and an ntfy node shows server, topic and
priority. A field marked as a credential renders as a picker over your stored
[secrets](operations.md) instead of a text box.
@@ -59,7 +57,7 @@ ports. See [Where a node's values come from](../concepts/values.md).
**Timeout** (Function nodes) is how many seconds the code may be *silent*
before it is stopped: it measures silence, not duration, so a node that yields
every few seconds can run for hours under a timeout of 300. Left empty there is
no limit, which is the default — set one where a node going quiet means it is
no limit, which is the default. Set one where a node going quiet means it is
stuck rather than working. A `0` says so explicitly.
**Code** is the editor. It saves as you type and applies on ⌘S; the node
@@ -71,10 +69,10 @@ instead.
Editing a shared node edits the copy every flow using it runs, which is the
point and also the caution.
!!! note "Not in the panel (yet)"
!!! note "Not in the panel yet"
`device` and `device_policy` which machine a node's code runs on are set
through the API rather than the panel. See
`device` and `device_policy`, which machine a node's code runs on, are set
through the API rather than the panel, with `PUT /flows/{name}`. See
[Remote workers](../code/workers.md).
## The flow panel
@@ -95,8 +93,8 @@ Click the canvas title to open the flow's own settings.
Click a wire. You get the last payload that went down it, when, and a sparkline
of its recent numeric history. You can also republish that value from the node
that produced it, which re-runs everything downstream the fastest way to test
a change without waiting for the real sensor.
that produced it, which re-runs everything downstream. It is the fastest way to
test a change without waiting for the real sensor.
## The dock