Clients take a flow's id or key: one resolver in the SDK, id first, explicit id:/key:, a warning for reads and a refusal for changes when a name means two flows, deleted flows found by their last key; sync creates by POST, retries a create race through the drift checks and reports the id; MCP gets create_flow and resolves every flow argument with the caller's token; displays show flow_name; an engine from before ids is named as such

docs/code/cli.md

@@ -153,6 +153,24 @@ is a fallback.
 `FLUKSIO_URL` and `FLUKSIO_TOKEN` override saved values; command options
 `--url` and `--token` override both.
 
+A client needs an engine at least as new as itself. An engine from before
+flow ids cannot create flows the way this client does, and the client says
+so and asks you to upgrade the engine.
+
+### Naming a flow
+
+Wherever a command takes a flow, pass its id or its key. A flow created
+before ids existed has its key as its id; a new one has an id like
+`f_k3q7m2xa`. The id is tried first, then the key, and an unknown name
+lists the closest keys.
+
+When a name is one flow's id and another flow's key, write `id:heating` or
+`key:heating` to say which. A command that only reads uses the id and warns
+on stderr. A command that changes something, such as `run` or `sweep`,
+refuses until you choose. `runs` and `export` also find deleted flows by the
+key they last had, and refuse a key several of them have had. `id:` always
+works, even for a deleted flow's history.
+
 ### `fluksio login`
 
 ```sh
@@ -198,7 +216,12 @@ inside the project's repository.
 
 Sync records source digests for [stage caching](../concepts/runs.md#stage-caching)
 and refreshes local workers, so edited imports are picked up. An unchanged
-flow reports `unchanged`. See the
+flow reports `unchanged`.
+
+Sync finds a flow by its declared key. The first sync creates it, and the
+engine gives it an id, which sync prints beside the key. Another engine gives
+the same flow another id, so the key is what your code and every instance
+share. See the
 [data science guide](../getting-started/data-science.md) for a complete example.
 
 ### `fluksio run`
@@ -275,7 +298,8 @@ instance without a served engine.
 fluksio runs --flow train --limit 10
 ```
 
-Lists recent runs, newest first. Omit `--flow` for all flows.
+Lists recent runs, newest first. Omit `--flow` for all flows. The flow
+column shows its key.
 `--local` reads the local instance.
 
 ### `fluksio cancel`
@@ -342,6 +366,8 @@ select columns, including dotted paths such as `final_metrics.train_loss`.
 
 Both support `--flow`, repeated `--run ID`, `--group`, `--status`,
 `--since`, `--until` and `--local`. The run ID joins results to metrics.
+Rows name the flow by its id in `flow` and its key in `flow_name`, and
+metric names keep the key, as in `train.loss`.
 An export stops at the newest 10 000 runs, and when a selection matches more,
 the CLI and the Python client warn how many were left out.