Docs for key renames: ids and keys in the flow concepts, the rename routes, events and 503s in the API reference, hooks during a rename, sync and run metrics after one; a pinned restore refused for its recorded key names that key in the 409

docs/concepts/flows.md

@@ -44,6 +44,26 @@ def process(temperature):
 
 The canvas shows cross-flow messages as labelled endpoints.
 
+### Ids and keys
+
+A flow has two names. Its **key**, such as `house`, is the namespace of its
+messages, so it is what other flows, dashboards and your scripts write. Its
+**id** says which flow it is and never changes. The editor's address, webhook
+URLs (`/hooks/<flow id>/...`) and the API's paths use the id. A flow from
+before ids existed has its key as its id, and a new one gets an opaque id such
+as `f_k3q7m2xa`. Dashboards have an id and a key in the same way.
+
+A superuser can rename a flow's key. Everything named under it moves along,
+so `house.temperature` becomes `home.temperature` in every flow and dashboard
+bound to it, together with its history, live values and queued work. What uses
+the id keeps working. Whatever names the old key from outside, such as a call
+to `/messages/house.temperature` or a script, has to be changed by hand. The
+whole engine pauses while a flow's key is renamed, see
+[Renaming the key](../interface/flow-editor.md#renaming-the-key).
+
+Deleting a flow frees its key. Its runs stay under the key it last had, and a
+new flow that takes the key starts with an empty history.
+
 ## Node types and payloads
 
 Function nodes run your Python code. Built-in nodes handle MQTT, HTTP,

docs/concepts/runs.md

@@ -216,7 +216,7 @@ such as `metric.final_metrics.train_loss`. A row names the flow by its id in
 `flow` and by its key in `flow_name`. History stays with the id, so a flow
 keeps its runs whatever its key is later, and a new flow that takes the key
 of a deleted one starts without them. Metric names keep the key, as in
-`train.loss`.
+`train.loss`, and a key rename moves them to the new one.
 
 Python returns the same rows directly. `flow` takes the flow's id or key,
 as everywhere in the client: