Canvas Annotations

Annotations are canvas-only items for documenting a workflow. Use them to explain assumptions, call out risk, leave handoff notes, or make a complex graph easier to understand.

Annotations are for humans. They do not run, pass data, validate configuration, or create executable flow.

Quick reference

Use an executable edge when data must flow between nodes. Use an annotation when you only want to explain or point.

Add annotations

Use either path:

1. Click the Sticky Note or Arrow button in the editor toolbar.
2. Right-click empty canvas and choose Add sticky note or Add arrow.

New annotations are saved with the workflow like other canvas items. Sticky Notes and Arrows sit behind executable nodes so they do not block node interaction.

Sticky Notes

Sticky Notes are editable documentation blocks on the canvas.

Edit text

• Double-click a note to edit it.
• Select one note and press Enter or F2 to edit from the keyboard.
• Press Cmd/Ctrl + Enter to save while editing.
• Press Esc to cancel the current edit.
• Use Copy text from the note context menu to copy only the note content.

Sticky Note text is capped to keep workflows fast and safe to save. Keep notes focused. For long documentation, link to an external doc instead of pasting the full document into the canvas.

Use markdown-lite formatting

Sticky Notes support lightweight formatting in read mode. Type plain text while editing; the note renders formatting after you save.

You can also right-click a note and use Formatting to insert common patterns such as Heading, Bullet, Checkbox, Bold, Italic, or Link.

Mention nodes and variables

Sticky Notes can highlight node and variable references so readers can connect the note to the workflow.

Use Insert mention from the context menu to insert a reference from workflow nodes. The toolbar braces button inserts a quick mention when available.

Mentions are documentation only. They do not bind data, execute templates, or change runtime behavior.

Add status badges

Sticky Notes can carry a small status badge:

• TODO - work still needed.
• Risk - something needs extra care before running or sharing.
• Decision - records why the workflow is built a certain way.
• Done - marks a documented task as complete.

Use the status button in the selected-note toolbar to cycle statuses, or right-click the note and choose Status for an explicit selection.

Attach notes to nodes

Attach a note when it documents a specific executable node.

1. Right-click the note.
2. Open Attach to node.
3. Choose the target node.

When the attached node is dragged or tidied, the note moves with it. If the target node is deleted, the note is kept and automatically detached.

Attachment is visual only. It does not create an edge, dependency, or data relationship.

Resize and fit

• Drag the resize handles to change note size.
• Use Fit to text from the toolbar or context menu to resize the note around its current content.
• Press Cmd/Ctrl + Shift + F when a single note is selected to fit it to text.

Fit to text is an estimate based on the note content. You can still resize manually afterward.

Toolbar and context menu

When a note is selected, the inline toolbar gives quick access to:

• Color swatches
• Status
• Detach
• Fit to text
• Insert mention
• Edit, save, and cancel
• Duplicate
• Delete

Right-click a note for the full menu: edit, copy text, fit, attach, status, formatting, insert mention, color, duplicate, and delete.

If a note is near the top of the canvas, the toolbar appears below the note so it stays reachable.

Keyboard shortcuts

Arrows

Arrows are visual pointers. They are not workflow edges.

• Resize the arrow box to change its length and angle.
• Right-click the arrow to change direction, line style, or color.
• Choose solid or dashed line style.
• Use arrows for visual guidance only; use edges when data must flow between nodes.

What annotations do not do

Annotations:

• Do not execute
• Do not count as runnable nodes
• Do not have input or output handles
• Do not affect workflow validation
• Cannot pass data downstream
• Cannot trigger, pause, filter, transform, or branch a run

If you need workflow data to move between nodes, create an edge. If you need a branch to pause, log, filter, or transform data, use the matching node instead.

Copying, duplicating, and tidy layout

Annotations behave like canvas items during editing:

• Duplicate or copy/paste keeps Sticky Note text, color, status, size, and attachment metadata.
• If you duplicate or paste both an attached note and its target node together, the copied note attaches to the copied target.
• If you duplicate only a note, it keeps its original attachment unless you change it.
• Tidy up layout moves attached notes along with their target nodes.

Marketplace behavior

When you list or sell a workflow, annotations clone with the workflow.

Buyers can see:

• Sticky Note text
• Sticky Note color, size, status, and attachment labels
• Arrow direction, style, color, and size

Do not put secrets, private webhook URLs, API keys, wallet-sensitive information, or non-public trading instructions in annotation text. Treat annotations as visible documentation for anyone who can view or clone the workflow.

Recommended uses

Good Sticky Notes:

• Explain why a node exists.
• Record assumptions, thresholds, and safe ranges.
• Mark a TODO before publishing.
• Warn that a node can send a message, broadcast a transaction, or spend funds.
• Tell marketplace buyers what they must configure after cloning.
• Link to external runbooks or source documentation.

Good Arrows:

• Point from a note to the node it explains.
• Emphasize a branch or fallback path.
• Show a conceptual relationship without creating executable flow.

Avoid using annotations as the only place where required runtime configuration is stored. If the workflow needs a value to run, configure it on the node.

Next steps

• Canvas Overview - editor layout and controls
• Connecting Nodes - executable data flow
• Marketplace Listing - what buyers receive