# Workflows (Automation)

Workflows are reusable automation templates you build from a group of canvas nodes. Once saved, they appear in the **Workflows Explorer** sidebar and can be dragged onto any project's canvas to replay them instantly.

## Building a workflow

1. **Create nodes on the canvas** — add images, videos, 3D models, or any content using **Shift+drag** from the Media Explorer, or right-click an existing node to use **AI Tools**.
2. **Connect them logically** — drag edges between nodes to define dependencies and data flow (see the infinite canvas editor docs for details).
3. **Select the group** — hold **Shift** and click nodes to multi-select, or drag a lasso around them.
4. **Group the selection** — from the selection toolbar, click the **Group** button. The nodes are wrapped in a cyan-bordered group.
5. **Convert to workflow** — inside the group's toolbar, you'll see a **Network** icon appear (amber border, workflow mode). The toolbar now shows a **Save to Workflows** button (bookmark icon). Click it to save the group as a reusable workflow.

When saving, the group snapshot (nodes + edges) is stored in Convex along with a thumbnail. The workflow is named after the group label.

## Workflows Explorer sidebar

The **Workflows Explorer** sidebar (right-click the **Workflows** item in the left sidebar to open) displays your saved workflows in two sections:

- **My Workflows** — workflows you created, searchable by name.
- **Organisation** — workflows shared by your org members (read-only, owned by others).

At the top, a search field filters both sections. Each workflow card shows:
- **Thumbnail** — a canvas-style preview (or a Network icon if no thumbnail).
- **Name** — the workflow label.
- **Node count & inputs** — e.g. "5 nodes · 2 inputs".
- **Org badge** — a Building2 icon if the workflow is org-shared.

**Right-click a workflow card** to:
- **Rename** — edit the name locally.
- **Share with [Org]** or **Remove from [Org]** — toggle org sharing (owner-only action).
- **Delete** — permanently remove the workflow.

## Workflow group appearance

Saved workflows have fixed amber styling to distinguish them from regular groups:
- **Border** — solid (non-dashed) amber-500/50.
- **Fill** — amber-500/10 (or amber-500/20 when selected).
- **Label icon** — a **Network** icon (rotated 90°) precedes the group name.
- **Label suffix** — shows "— N inputs" if the group has parameterized input nodes.

You **cannot change the color** of a workflow group (unlike regular groups). Double-click the label to rename it; changes propagate to the saved workflow in Convex.

## Input node parameterization

Workflow input nodes are the roots of the data flow — they're the canvas nodes the workflow expects as starting points when you drag it onto a new canvas.

When you build a workflow:
1. **Identify input nodes** — root nodes with no parent edge dependency (e.g. image references, initial prompts).
2. **The system tracks them automatically** — when you save, `workflowInputNodeIds` is populated.
3. **Users instantiating the workflow** can **drag-map** these inputs by clicking nodes on the canvas as they set up the replay.

Input nodes are displayed in the workflow group label as a count, e.g. "Flow — 2 inputs".

## Instantiating a workflow on the canvas

To place a saved workflow on the canvas:

1. **Open the Workflows Explorer** if not visible — right-click the left sidebar's **Workflows** item.
2. **Find the workflow** — search by name or scroll the list.
3. **Drag the workflow card onto the canvas** — the entire workflow (nodes + internal edges) is placed where you drop it.
   - The first node appears **center-aligned** to your drop position (drag from top-left to place from that corner instead).
   - All internal edges are preserved; the workflow is fully functional as a unit.
4. **A toast confirms** — e.g. "Flow placed on canvas" (success message, 2 seconds).

The instantiated workflow becomes a live workflow group node on the canvas. All child nodes are selectable, editable, and can feed into downstream nodes or run independently.

## Sharing a workflow with your Organization

Only the workflow owner can share it. To share:

1. **Right-click the workflow card** in the Workflows Explorer.
2. **Click "Share with [Org]"** (e.g. "Share with Acme Studio").
   - A toast confirms: "Shared with organisation" (success).
   - The workflow's `orgId` is set to your org ID in Convex.
3. **Organisation members see it** — the workflow now appears in the **Organisation** section of their Workflows Explorer.
   - They can read and instantiate it, but cannot rename or delete it.
   - They see a **Building2 icon** badge on the card indicating org sharing.
4. **To un-share** — right-click again and click **"Remove from [Org]"**.
   - The workflow reverts to private (personal use only).

**Note:** Community (public) workflow sharing is not currently built; org sharing is limited to your organisation members.

## Org members & departed-member cleanup

When a member leaves your organization, their org-shared workflows are automatically hidden from the Workflows Explorer (filtered out during the query). Org admins can forcibly un-share a departed member's workflow if needed using an admin escape hatch in Convex.

## Workflow runs & execution

Workflow groups can be **run** by clicking the **Play** button in their toolbar (appears once a workflow is created). Running executes the internal chain:

1. **Input nodes** receive values from the canvas or user input.
2. **Each step node** runs, outputting results.
3. **Leaf nodes** (final outputs) appear as new nodes on the canvas.

Runs are atomic — they complete as a unit and do not interact with downstream canvas nodes unless explicitly connected via edges outside the group.