docs

docs/concepts/values.md

@@ -1,67 +1,60 @@
 # Where a node's values come from
 
-A node function is called with one argument per thing it needs, and every one
-of them is declared somewhere you can see. There are two kinds.
+Function nodes receive values as named arguments. Each comes from a message
+port, a node setting or a Python default.
 
 ## Ports: what the graph carries
 
-A port binds to a message name. Whatever last published that message is the
-value the node is called with, and the wiring follows from the name rather than
-from a line somebody drew.
+A port binds to a message name and reads its current value. Declare inputs
+`reading` and `setpoint`, and output `heat`:
 
 ```python
 def process(reading, setpoint):
     return {"heat": reading < setpoint}
 ```
 
-with `reading` and `setpoint` as inputs and `heat` as an output.
+Matching message names connect nodes. A port can have a different name from
+its message: bind port `reading` to `house.temperature`, for example.
 
 ## Settings: constants of this node
 
-A setting is a value that belongs to this node's code rather than to the graph:
-how many retries, which unit, how long to wait. It is typed into the node's
-**Settings** section, stored with the flow, and arrives as an argument like a
-port:
+Use settings for values that stay fixed while the flow runs: units, retries,
+thresholds. Add them in the Function node's **Settings** section; they are
+stored with the flow and passed beside the ports:
 
 ```python
 def process(reading, unit="C"):
     return {"shown": reading if unit == "C" else reading * 1.8 + 32}
 ```
 
-Because both arrive by name, a setting cannot share a name with a port. The
-node reports it rather than picking one.
+With a `unit` setting, its configured value is passed to the function. Without
+one, the Python default applies. A setting cannot share a name with a port.
 
-Settings are part of the flow document, so changing one is an edit that gets
-published, not something that happens at runtime. **A value that should change
-while the flow runs is a message, not a setting.**
-
-There is no `global` and no `flow` context. A constant several nodes need is a
-node that provides it: one place it is set, an ordinary message out, and every
-consumer visibly downstream of it.
+Changing a setting edits the flow draft, so publish it to apply the change.
+For a value that should change at runtime, use a message. To share a constant
+between nodes, publish it from one node and let the others consume it.
 
 ## Flow inputs: what arrives from outside
 
-Some messages are not computed by any node in the flow, such as a dashboard control
-writes them, the API publishes them, a batch run passes them in. Declare those
-as the flow's **inputs**, with the value they start from:
+Dashboard controls, the API and batch runs can supply messages without a
+producer node. Declare them as **Inputs** in the flow settings:
 
 ```json
 {"inputs": [{"spec": {"name": "setpoint", "dtype": "float"}, "initial": 21.0}]}
 ```
 
-Without that, the node reading `setpoint` waits for something nothing provides,
-and the canvas says so. With it, the flow starts from 21.0 and whatever writes
-the message afterwards takes over.
+The initial value seeds an unset live message. Later publications take over;
+changing the starting value does not overwrite a value already in state.
+Use **Publish this value now** in the input row to send it immediately.
 
-The canvas draws each one as a labelled endpoint feeding the nodes that read
-it, the same way it draws a dashboard tile or another flow, so a value never
-appears from nowhere. They are edited in the flow's own panel.
+The canvas draws flow inputs as labelled endpoints. Without a producer or
+declared input, a consuming node reports `unconnected_input`.
 
-A batch flow's inputs are also its run parameters, and its **outputs** name what
-a run reports as its result; see [Runs](runs.md).
+A batch flow's inputs are run parameters. Its **Result** section selects the
+messages returned when the run finishes. See [Runs](runs.md).
 
 ## See also
 
-- [Flows, nodes and messages](flows.md) — how the graph is built from the names
-- [Keeping state in a flow](state.md) — a value a node reads *and* writes
-- [Writing node code](../code/nodes.md) — the practical side
+- [Flows, nodes and messages](flows.md)
+- [Keeping state in a flow](state.md)
+- [Writing node code](../code/nodes.md)