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/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.