Merge branch 'ids-clients'

docs/code/agents.md

@@ -41,13 +41,20 @@ page.
 | Inspect values | `get_flow_state`, `get_message_history` |
 | Inspect the instance | `list_secrets` (names only), `get_modules`, `get_health`, `get_metrics`, `list_failures`, `list_runs` (live cascades) |
 | Inspect devices | `list_devices`, `get_device` |
-| Edit flows | `save_flow`, `save_node_source`, `validate_flow`, `publish_flow`, `discard_draft`, `delete_flow` |
+| Edit flows | `create_flow`, `save_flow`, `save_node_source`, `validate_flow`, `publish_flow`, `discard_draft`, `delete_flow` |
 | Operate flows | `run_flow`, `trigger_node`, `start_flow`, `stop_flow`, `pause_flow`, `resume_flow`, `cancel_node` |
 | Install node packages | `apply_modules` |
 
 Tools call the same API as the browser. Drafts, validation, version checks,
 and superuser restrictions apply. Secrets cannot be read back.
 
+A tool's `flow` argument is the flow's id or its key, resolved from the flows
+the agent's user can list, as the [CLI does](cli.md#naming-a-flow). When a
+name could mean two flows, a reading tool uses the id and adds a `warning` to
+its answer, and a tool that changes something refuses until the agent writes
+`id:<x>` or `key:<x>`. `create_flow` makes a new flow, under an id the server
+issues. `save_flow` only changes an existing one and cannot change its key.
+
 A useful workflow: ask the agent to inspect the flow, save a draft, and
 validate it. Review the draft before asking it to publish. The agent has
 a publish tool, so make your intent explicit.

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.
 

docs/code/workers.md

@@ -73,7 +73,7 @@ removed; pass credentials through [Secrets](../interface/operations.md#secrets).
 
 ## Send a node to it
 
-Set these fields on a node through `PUT /api/v1/flows/{name}`:
+Set these fields on a node through `PUT /api/v1/flows/{id}`:
 
 ```json
 {

docs/concepts/runs.md

@@ -218,7 +218,8 @@ 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`.
 
-Python returns the same rows directly:
+Python returns the same rows directly. `flow` takes the flow's id or key,
+as everywhere in the client:
 
 ```python
 from fluksio.sdk.client import Client
@@ -249,8 +250,9 @@ Client().import_runs([{
 }])
 ```
 
-The flow must exist, and parameters are checked against its inputs. Over the
-HTTP API an entry's `flow` is the flow's id. Repeated imports of the same
+The flow must exist, and parameters are checked against its inputs. The
+Python client takes the flow's id or key for `flow`. Over the HTTP API an
+entry's `flow` is the flow's id. Repeated imports of the same
 `external_id` reuse the existing record. Imported runs
 have no code commit or digest because the engine did not execute them.
 Entries may also carry metric points and base64-encoded artifacts; see the

docs/reference/node-types.md

@@ -458,7 +458,7 @@ targets cannot answer before training starts. The panel follows the run and
 shows the model's exact match, coverage and threshold, and its exact match on
 the tests, once it ends. **Use this model** sets the new model as `model` in
 the draft, and publishing puts it live. `POST` and `GET` on
-`/flows/{name}/nodes/{id}/train` start a training run and read the latest one.
+`/flows/{flow id}/nodes/{node id}/train` start a training run and read the latest one.
 
 Training needs wren's `train` extra, which brings JAX, where the run executes:
 in **Modules** (see [Packages](../code/nodes.md#packages)) or on a worker. List