solai-flow-editor

SolAI Flow Editor

Use this skill to interact with live Contextual flows through the ctxl-flow-editor MCP server.

When to invoke

Invoke this skill before any mcp__ctxl-flow-editor__* tool call that inspects or modifies a flow. The only exempt orientation tools are info and list_sessions (used to answer "is the server up / which flows are open?"). Everything else is gated, including reads.

Trigger phrases — load the skill as soon as user intent matches any of these against a live flow:

• Edit: add, change, update, move, wire, connect, delete, rename, configure, set, fix, group, copy a node / wire / property / code / tab
• Inspect: look at, check, read, validate, search flow contents
• Test: create inject or contextual-test nodes, set up test data

The trigger is intent to work on a flow, not the literal word "edit". A request like "add some comment nodes to my hello world flow" qualifies — load the skill before the first editor_state / flow_read / type_info / import call.

Why this matters: loading this skill brings node-reference.md, sequencing rules (especially intra-batch placeholder IDs and cross-batch wiring — see Sequencing rules step 3), and the silent-failure catalogue into context. Skipping it produces failures the MCP server does not surface clearly: dropped cross-batch wires, intra-batch placeholder-ID collisions that silently drop a node, invalid id types (numeric, empty string) that silently drop a node, node_update wire-mutations that report success but do nothing, wrong node types, broken tray_open→tray_read sequences, malformed editable-list defaults.

Setup Check

The MCP server must already be running in the user's own terminal — never start it yourself. Any process started via shell from this context is ephemeral and dies immediately.

If mcp__ctxl-flow-editor__* tools appear in the deferred tool list, the MCP server is running — but this does not mean any flow sessions are active. Load the tool schemas and call list_sessions to check for live browser connections. Only proceed with flow editing if list_sessions returns sessions. If it returns none, the user needs to open the target flow in their browser first.

If those tools are not available, tell the user to run this in their own terminal first:

ctxl mcp serve --config-id <config-id>

Read node-reference.md now — this is not optional. It contains node-specific foot-gun warnings that type_info does not surface: e.g. query-native-object's query: "" is a guaranteed runtime JSON.parse("") throw despite being the registry default (canonical match-all form is "{}"); the loop node has three silent setup-gates that fail to a port-0-only firing; http-response's configured statusCode silently overrides msg.statusCode; Native Object nodes have TypedInput companion-field pairs that runtime Zod-rejects when absent even though type_info marks them required: false. type_info reports registry defaults; node-reference.md warns you when those defaults will throw at runtime. Skipping it ships silent foot-guns the runtime catches but type_info does not.

What this MCP server is

The ctxl-flow-editor MCP server bridges this AI session to an active browser-based Contextual Flow Editor session. Changes made through these tools are reflected live in the browser editor — you are not editing a file.

A flow session only exists when the flow is open in a browser tab. list_sessions reflects live browser connections. If a flow is not listed, the user needs to open it in their browser before you can work on it. The correct URL to open the Flow Editor is https://<flow-id>.flow.<tenant-id>.my.contextual.io/.editor — without /.editor, HTTP-based flows will serve their root endpoint instead of opening the editor. Always resolve the tenant ID by running ctxl config current --json (via Bash) before giving the URL to the user — never hand them a URL with <tenant-id> as a literal placeholder.

Terminology

Use these terms consistently. Never use internal engine terminology.

Term	Meaning
Flow	The entire logical unit being edited — all tabs, subflows, config nodes, and global state together. When a user says "my flow" they mean the whole thing.
Tab	A single canvas page inside the Flow Editor. The editor has a row of tabs along the top. Each tab contains its own nodes, wires, and groups. In tool parameters, tabId refers to a tab or subflow ID.
Subflow	A reusable component with internal nodes. Appears in the palette and can be instanced onto any tab. Opens as its own tab when editing.
Subflow instance	A single node placed on a tab that references a subflow. Its type is subflow:<definition-id>.
Config node	A shared configuration node not tied to any specific tab (no z property). Referenced by other nodes.
Active tab	The tab currently visible in the editor.

Platform framing

This is a proprietary platform. Do not apply assumptions from public knowledge of other flow-based tools. Source-of-truth precedence when uncertain about node behaviour or platform conventions:

1. type_info (if a live session is active) — the connected editor's authoritative definition for the specific node type
2. node-reference.md and this SKILL.md — kept current with empirically-verified build-time reality via ongoing verification against the live platform; canonical for node-level behavior, authoring patterns, and sequencing rules
3. solai-knowledge — for platform/runtime behavior not in (1) or (2)

For genuinely cross-cutting queries, run multiple sources in parallel — the answers are complementary.

Available tools (by category)

• Read state: editor_state, flow_read, search, validate, type_info, info, logger_messages, result_read
• Navigate: navigate, select
• Write: import, wire, node_update, delete, move, copy, group — note: delete requires useSelectionAction as a boolean, not a string
• Tray (node properties panel): tray_open, tray_read, tray_write, tray_commit
• Code (function/template node editors): code_read, code_write, code_edit, code_grep, code_patch

Important behaviors

• import is placement only — never include cross-batch wires: Any wire targeting a node outside the imported batch is silently dropped with no error, always, regardless of whether the target exists. Do not include cross-batch wires in import payloads and "fix them if they drop" — they will always drop. Always wire after import using the wire tool. Intra-batch wires (both ends in the same import call) are the only wires that survive import.
• Navigation side-effects: Many tools (import, node_update, navigate, code_edit, etc.) navigate the user's viewport, switch tabs, and change selection in real-time. Be deliberate — don't jump the user around unnecessarily.
• Concurrent editing: The user may be editing at the same time. Warn before editing code in a node they may be actively working in.
• Saving: Changes are live but not saved until the user acts. Do not remind by default — mention Save the Flow only when needed (before run/test/verify, or when context is unclear). The button in the Flow Editor UI is labelled Save — never use the word "Deploy" to refer to this action. Deploying means binding a flow to an Agent for production execution, which is a separate step.
• Testing: You cannot run flows or view test results. You can create contextual-test nodes and inject nodes for manual testing.
• "logs"/"logger" means the debug drawer here. In the Flow Editor, "check the logs/logger" almost always means the current session's debug drawer → logger_messages (ephemeral, editor-only). This is distinct from Tenant Logs (ctxl logs in the solai-cli skill — persistent, from deployed agents, CLQL-queryable). Switch to Tenant Logs only on explicit cues (agent / deployed / prod / over time / session id / query / CLQL); when context and cues conflict, ask. See node-reference.md → "logs" vs. "logger".
• One wire per output port: Do not connect multiple wires from the same output port to different destinations. log-tap nodes must be wired inline (A → log-tap → B), never branched off a shared output.
• Navigate before importing: import always targets the active tab. Call navigate to switch to the correct tab before each import. Be aware that tray_read, code_read, node_update, and navigate with action: "reveal" can switch the active tab as a side-effect — re-navigate if uncertain.

Sequencing rules

Follow these on every task:

1. Call list_sessions if the target flow ID is unknown
2. Call editor_state to confirm the active tab before any write operation
3. Use unique placeholder IDs for intra-batch wiring — do not pre-generate hex IDs. When wiring imported nodes to each other in a single batch, each node you intend to wire to needs an id field in the payload. The editor replaces it with a generated ID on placement; the placeholder is used only to resolve the batch's wires arrays during the call. Any short string works — a counter (n1, n2, …) or descriptive labels (in, parse, log). IDs must be unique within the batch: if two nodes share an id, only one is placed and the duplicate is silently dropped (the import response's nodeCount will be lower than your input, with no error). Numeric IDs and empty-string IDs are silently rejected the same way. If you can't trust yourself to maintain a counter across a payload built in pieces, python3 -c "import secrets; print(secrets.token_hex(8))" is a cheap way to guarantee uniqueness — but that's the only reason to use it; the platform does not require hex IDs at import. Cross-batch wires are a separate matter — see the "import is placement only" rule above.
4. Before any import or node_update of a node type you haven't used in this session: first confirm node-reference.md has been read this session and consult its entry for this node type (the foot-gun warnings live there, not in type_info); then call type_info to confirm the property shape. Both are needed — type_info reports defaults, node-reference.md warns when those defaults will throw at runtime. Any field showing defaultValue: "[Circular]" in the propertyMap is an editable-list array — always set it to [] explicitly in the import payload. This is reliable across all node types; [Circular] is a JSON serialisation artifact, not a missing value. For Native Object nodes: before building the import payload, also verify that any upstream function or change nodes do not store data on reserved msg keys (typeId, objectId, query, search, filters, property, order, fields, etc. — see the full list in node-reference.md). Use nested paths like msg.payload.* or msg.data.* instead. Setting a reserved key on msg silently overrides the downstream node's configured value.
5. Call navigate to the target tab before calling import
6. Call validate scoped to the affected tab after every batch of changes. Treat the results as follows:
   • Newly introduced errors — block completion, fix immediately before continuing
   • Newly introduced warnings — assess severity before acting:
     • Warnings that indicate missing error handling or broken flow patterns (e.g. require-catch-nodes) are runtime risks — fix these before reporting the task as done
     • Cosmetic, structural, or naming warnings — surface to the user and leave the decision to them
   • Pre-existing issues — report for awareness only, do not auto-fix
   • Never summarise as "zero errors" if warnings exist — always report errors and warnings separately

Editing code

Use code_edit (find-replace) first. If a clean replace is not possible, use code_patch (unified diff). Use code_write (full replacement) only as a last resort. For rewrites of 30+ lines, tell the user first.

code_read → understand content → code_edit

Changed lines are highlighted in the editor. Do not call tray_commit after code edits unless the user explicitly asks — leave the tray open for review.

Canvas positioning

• Lay out nodes with generous spacing: 275px horizontal, 70px vertical for stacked nodes
• Never stack nodes at the same coordinates
• Flows should not exceed 1000px wide — wrap to a second line if needed
• Nodes are positioned by their center point
• When inserting among existing nodes, use move to make space before importing

Node labels and the l parameter

• l: false hides the label, showing only the node's icon
• Do not set l: false by default — only collapse labels when the node's purpose is clear from its icon alone, or the user requests it
• Match the label patterns already used in the flow

Reading node configuration

Goal	Tool	Notes
Full live field model with values	tray_open → tray_read	tray_open first, then tray_read. Resolves TypedInput state, editor values, tab associations.
Raw node data without side-effects	flow_read with action: "node"	Lightweight. No tray interaction. Missing live editor values and missing wires (downstream targets — both action:"node" and action:"object" omit them).
Wire / connection audit on a single node	flow_read with action: "tab", includeNodeDetails: true	Returns the full tab — pick the target node from the nodes array. Only path that includes wires per node.
Code editor content	code_read	Paginated. Works while expanded editor is open.
Node type defaults and help	type_info	Use before creating nodes or to understand a type's properties.

Wiring discipline

• Use wire for every wire change — node_update silently no-ops on the wires field. This applies whether you're adding a wire to a node that has none, redirecting an existing wire to a different target, or clearing wires entirely. Both node_update changes:{wires:...} and node_update patch:[{op:"replace", path:"/wires", ...}] return status:"ok", updated:["wires"], valid:true while leaving wires unchanged. The only signal that nothing happened is reading the node's wires back. Use the wire tool's add / remove operations exclusively for any wire modification. node_update is correct for non-wire properties (name, func, configuration fields) only.
• After any wiring changes, call flow_read on the affected tab and audit wires on every node added or modified in this task
• Trace each changed path end-to-end from entry node to terminal. Scope to paths in focus, not the entire flow.
• Never diagnose wiring from screenshots alone. Long wires running across the canvas can visually appear to originate from nearby nodes. Before accepting a suspected fan-out or race condition, call flow_read and check the node's wires array and outputs count. A wire that looks like a second output from a node may be a long wire from an upstream node passing through that region of the canvas.
• Route bypass wires off-axis. When a branch skips a section of the chain (e.g. an early-exit path bypassing several nodes to reach a terminal), run that wire at a y-level clearly offset from the main chain — not along the same horizontal plane as the nodes it bypasses. Wires that share the y-level of nearby nodes are easily mistaken for connections to those nodes.

Deployment discipline

Batch size is governed by payload size, not node count. In testing with hefty function nodes (20+ lines of real code each), single imports of 10, 15, and 20 nodes all landed cleanly. The failure mode observed at the extreme was an MCP connection timeout — not silent node loss. The practical limit appears to be the MCP round-trip timeout (~30s), not a node count ceiling.

Guidelines:

• Comment/stub nodes: no meaningful limit observed up to 20
• Function nodes with substantial code: up to 20 landed reliably in a single import
• If a timeout occurs: split the batch and retry — no partial writes were observed; it's all-or-nothing
• After each import, always verify nodeCount in the response matches the number of nodes you sent. A mismatch indicates one or more nodes were silently dropped — common causes are duplicate placeholder IDs within the batch, invalid id types (numeric, empty string), and malformed payload shapes. Investigate before continuing.
• Never work from memory — always read current state before acting
• Every tab needs error handling: catch → log-tap (error) → http-response 500 or contextual-error

Direct property updates

Use the tray workflow for most property changes. Use node_update when the tray is not open and the change does not need user review (e.g. renaming a node). Note that renaming changes rendered width — use move afterward if needed.

node_update auto-commits immediately without opening the tray. If the target node's tray is already open with pending changes, use tray_write instead.

Tray workflow

tray_read → tray_write (one or more calls)

Only call tray_commit when the user explicitly asks to save or commit. Otherwise leave the tray open for review.

tray_read does not auto-open the tray — always call tray_open first, then tray_read. For editable lists, prefer semantic row selectors from tray_read(includeListItems: true). Treat warningCount/warnings on tray_write responses as a sign to re-inspect tray state before continuing.

When reading across multiple nodes, moving from tray to tray is fine. Before switching to non-tray tools on a different node, close with tray_commit action: "cancel" — unless you made edits, in which case leave the tray open for review.

Creating nodes

Method	When to use
import	Default. You control coordinates and wiring. Navigate to the target tab first. Follow with wire to connect to existing nodes.
interactiveInsert	Only when the user explicitly asks for interactive/manual placement.

Always call type_info before building node objects for import.

Key response fields

Check these after mutation tool calls:

• previousTrayTarget — ID/type of a tray displaced by the operation
• autoCommittedPreviousTray — whether displaced tray changes were auto-saved
• closedExpandedEditor — whether a fullscreen editor was closed
• uiFeedback.revealedNode — node the editor navigated to after the operation
• uiFeedback.selectedNodeIds — nodes selected after the operation

End-to-end flow guidelines

Wiring responsibility

• When suggesting more than one node for an end-to-end flow, always connect them with correct wires end-to-end
• Wiring is your responsibility — nodes should be connected when placed on the canvas
• Before finalizing any node creation, verify: did I connect all nodes? If not, go back.
• Double-check that log-tap nodes are included at key steps
• Double-check that function nodes are included at key steps around http-get, http-post, http-put, http-patch, http-delete

Flow patterns

• Event-based flows: contextual-start → (nodes) → contextual-end
• HTTP flows: http-in → (nodes) → http-response
• Every contextual-start output must be wired and must eventually reach a contextual-end
• Every wire path must eventually reach a terminal node

Custom node reference

Node	Use
contextual-start	Entry point for every event-based flow (not HTTP)
contextual-end	Terminal for every event-based flow (not HTTP)
contextual-error	Error terminal for both event and HTTP flows
send-to-agent	Send messages to a separate Contextual Agent/Flow
http-in	Entry point for HTTP flows
http-response	Terminal for HTTP flows — set status codes appropriately
log-tap	All logging — replaces debug node entirely
catch	Error handling — see catch node rules below

Output format

Return a concise summary: what changed, node IDs affected, validation result. Do not return raw JSON or full flow dumps.