{"id":103352,"plugin_id":"plugin_asdk_app_6aedf6ea2fac819180910f8b98663c77","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-11-18T06:19:21.537Z","digest":"f4812d7121329691994241712ba14ea6eee953c13397a9cc8c3d4d8f7dc97c70","against":null,"payload":{"description":"Clay workflows — version history: view snapshots, see what changed, and restore or undo a previous state. Use when the user mentions snapshots or asks to undo an edit.","included_files":[],"name":"workflows-snapshots","skill_md_contents":"---\nname: workflows-snapshots\ndescription: 'Clay workflows — version history: view snapshots, see what changed, and restore or undo a previous state. Use when the user mentions snapshots or asks to undo an edit.'\nallowed-tools: Read\n---\n\n# Workflow snapshots & version history\n\nBefore using this skill, read the `clay` entry skill if you haven’t already this session, and follow its access guidance.\n\nSnapshots are immutable, point-in-time captures of the entire workflow graph — nodes, edges, prompts, scripts, tools, and positions.\n\n## Key concepts\n\n- **Automatic creation**: after every graph-mutating node edit\n  (`clay workflows nodes` create|update|delete) and when a\n  run starts. `data[0]` is newest-by-`createdAt`, **not** necessarily the current\n  graph. Sharing/binding a trigger onto an existing node does **not** snapshot —\n  undo that create by deleting the trigger, not restore. Settings-only trigger\n  update/delete also do not snapshot — revert or recreate the settings; do not\n  delete the trigger and do not restore. `graph format` takes two snapshots when\n  validation has no errors (pre-layout, then post-layout); details under Undo.\n- **Restore does not reshuffle the list**: `snapshots restore` rewrites the draft but does not create or reorder snapshots. Duplicate hashes reuse the existing row without updating `createdAt`. After a restore, `data[0]` can be a later history entry that is not the current graph, so the next edit's `data[1]` is often that stale entry rather than the pre-edit graph. Compare the latest snapshot to the current graph (or find the list row that matches) before treating `data[1]` as the undo target.\n- **Content-addressed**: Each snapshot has a SHA-256 hash of its contents. Identical workflow states deduplicate to the same hash\n- **Immutable**: Once created, a snapshot's graph content never changes\n- **Run isolation**: Runs are pegged to a specific snapshot. Editing the workflow doesn't affect in-flight runs\n\n### Draft-history vs published versions\n\nThe same snapshot table holds two roles:\n\n| Role                  | When                                  | Purpose                                                                                |\n| --------------------- | ------------------------------------- | -------------------------------------------------------------------------------------- |\n| **Draft-history**     | Auto on edits / run start             | Undo log and run pegging. No release number.                                           |\n| **Published version** | User clicks **Publish** in the editor | Numbered release (`version`, optional `name`). Becomes the live graph automation runs. |\n\nPublishing marks a snapshot of the current draft as a numbered release; it does not create a separate store. See the workflows entry-point skill's `publishing.md` for draft vs live.\n\n**This skill is for undo/history** (`list` / `get` / `restore`). Publishing is a separate command (`clay workflows publish`). `clay workflows snapshots list` returns only the most recent snapshots (newest first) and is not a complete or reliable index of published versions — an older release can fall outside its window. To map a version like \"V4\" to its snapshot id (e.g. to filter runs by version), use `clay workflows versions list <workflowId>`, which lists every published version with its `number`, `label`, and `id`; select by the unique `number` for a `V{n}` version (or by `label` for a named one) and use that `id`.\n\n## CLI reference\n\nFor tool access or authentication problems, read the `clay` entry skill before continuing.\n\n### List recent snapshots\n\n```bash\nclay workflows snapshots list <workflowId>\n```\n\nReturns `{ data: [...] }`, newest first, each with `id`, `hash`, `createdAt`, and\n`nodeCount`/`edgeCount`. So `data[0]` is the most recent snapshot by `createdAt`,\nwhich may not be the current graph (see restore above). This list is capped at the\nmost recent snapshots — to look up a published version, use `versions list` (below).\n\n### List published versions (label → snapshot id)\n\n```bash\nclay workflows versions list <workflowId>\n```\n\nReturns `{ data: [...] }` of every published version, ordered by version `number`\ndescending, each with `id`, `number`, `name`, `label`, and `publishedAt`. This is the\ncomplete, reliable index for mapping a version the user names (\"V4\", or a published name)\nto its snapshot `id` — e.g. to filter runs by version. Published names are not guaranteed\nunique, so a `label` can match more than one entry; prefer the unique `number`\n(`select(.number==4)`) when the user names a `V{n}` version, and only match on `label` for a\nnamed version. Unlike `snapshots list`, it is not\ncapped and excludes draft-history snapshots. Note the highest `number` is not necessarily\nthe currently-live version: restoring an older version and republishing reuses that\nversion's number, so it can outrank later ones. To find which version a run actually used,\nread `workflowSnapshot.id` from a recent run row (`clay workflows runs query run` / `runs list`) rather than assuming `data[0]`.\n\n### Show a snapshot (whole graph, or one node)\n\n```bash\nclay workflows snapshots get <workflowId> <snapshotId>\nclay workflows snapshots get <workflowId> <snapshotId> --node-id <nodeId>\n```\n\nReturns the full captured graph: `nodes` (with types, prompts, code, tools) and\n`edges`. `--node-id` narrows `nodes` to a single node (edges are left intact).\n\n### Diff two snapshots\n\nThere is no built-in diff. Fetch both and compare with `jq` — but this raw `diff`\nis the underlying mechanism, not the thing you show the user:\n\n```bash\nclay workflows snapshots get <workflowId> <oldSnapshotId> | jq '.nodes' > old.json\nclay workflows snapshots get <workflowId> <newSnapshotId> | jq '.nodes' > new.json\ndiff <(jq -S . old.json) <(jq -S . new.json)\n```\n\n**Translate the diff into a plain-language change summary** rather than pasting the\nraw `diff` output — e.g. \"Node _Find Email_'s prompt changed; the edge _Research →\nDraft_ was removed; a new _Score Lead_ agent node was added.\" When the change alters\nthe graph's structure (nodes or edges added/removed/rewired), render before/after\nMermaid diagrams so the user can see it, not just read it (see the workflows\nentry-point skill's `presenting.md`).\n\nThe only built-in diagram command always renders the workflow's **current** graph:\n\n```bash\nclay workflows diagram <workflowId> | jq -r '.diagram'   # always the current graph\n```\n\nThere's no diagram command for an arbitrary snapshot id, so hand-write a small\nnode/edge list from that snapshot's `nodes`/`edges` for its side. Label the diagrams\nby the direction of the change: \"before\" is the state you're changing _from_, \"after\"\nis the state you're ending up _with_ — and use the command above for whichever side is\nthe current graph. When previewing a restore (see \"Restore to a snapshot\" below), the\nrestore overwrites the current graph with the snapshot, so the current graph is the\n\"before\" and the snapshot you're restoring to is the \"after\".\n\n### Restore to a snapshot\n\n```bash\nclay workflows snapshots restore <workflowId> <snapshotId>\n```\n\nRestores the workflow to the exact state captured in the snapshot. This replaces\nall current nodes, edges, prompts, scripts, and tools. Restore is destructive and\ndoes NOT snapshot the current graph first, and does **not** move the restored\nsnapshot to the top of `list` — `data[0]` can still be a later history entry.\nThe pre-restore state is recoverable only if a later edit or run already\ntriggered a fresh snapshot capturing it (snapshots are taken automatically\n**after** each graph-mutating edit and at run start). If the current graph has\nunsnapshotted changes you might want back, run `snapshots list` first and note\nthe snapshot that **matches** the current graph, not blindly `data[0]`.\n\n**Restore ≠ publish.** Restore rewrites the **draft** only. It does not change which\nsnapshot is live, and undoing an edit does not roll back live automation. If the\nuser wants live triggers to match the restored draft, they must **Publish** again\nin the editor (see the workflows entry-point skill's `publishing.md`).\n\n**Before restoring, show the user what will change.** Summarize the difference\nbetween the current graph and the target snapshot in plain language, and — when the\nstructure differs — show before/after diagrams (see \"Diff two snapshots\" above),\nso the user can confirm the revert before it destructively overwrites the current\nstate. After restoring, render the restored graph so they can see the result.\n\n## Common workflows\n\n### Undo the last edit\n\nEvery **graph**-mutating write schedules a snapshot **after** it completes — fire-and-forget,\nso the new row may lag. Do **not** assume `data[0]` is the current graph or that `data[1]` is\nthe pre-edit graph.\n\nTrigger create only snapshots when it allocates a **new** canvas node. Sharing an existing\n`workflowNodeId` is not in the snapshot hash — undo that create with\n`clay workflows triggers delete`, not restore. Settings-only\ntrigger update/delete also are not snapshotted: revert or recreate the settings; do not\ndelete the trigger and do not restore.\n\n`graph format` is two steps when validation has **no errors**: a **pre-layout** snapshot is\nawaited, then a **post-layout** snapshot is scheduled. Restore the pre-layout id (same\nnodes/edges, different positions). If validation had errors, the pre-layout snapshot is\nskipped — `.data[1]` may be an older unrelated snapshot; do not restore it. If the graph\nhad no prior snapshot, wait until the post-layout row has landed before treating\n`.data[1]` as the undo target.\n\n**Compare `snapshots get` vs the current graph** (`clay workflows graph get --mode full`) to tell current from newest-by-`createdAt`. If no\nrow matches, the post-edit snapshot may still be in flight — poll or restore `.data[0]`\n(step 4); do not search for a snapshot of the unsnapshotted current graph. Poll by repeating the snapshot list operation rather than running a shell\n`for`/`seq`/`sleep` loop.\n\n```bash\nclay workflows snapshots list <workflowId> | jq -r '.data[0].id'   # newest — not always current\nclay workflows snapshots list <workflowId> | jq -r '.data[1].id'   # next older — not always pre-edit\nclay workflows snapshots restore <workflowId> <snapshotId>\n```\n\n1. **Find `before_id` before the edit:** if `.data[0]` matches the current graph, `before_id`\n   is `.data[0].id`. If not, walk the list until a row matches — that id is `before_id`. If\n   none match, there is no restorable pre-edit snapshot; do not pass a null id to `restore`.\n2. **With `before_id` (node/trigger edits):** after the write, restore **`before_id`**. Do not\n   restore `.data[1]` as a proxy — after a restore that id can be a later history entry.\n3. **With `before_id` (after `graph format`):** restore **`before_id`** only if that id\n   matched the current graph **before** format. If you had no matching snapshot before\n   format, call `list` until `.data[0]` matches the current (post-layout) graph, then\n   restore `.data[1].id` **only if it is the pre-layout graph** (same nodes/edges, different\n   positions). If validation had errors, that pre-layout row was never created — `.data[1]`\n   can be an older unrelated snapshot; if so (or if `.data[1]` is missing), report no\n   restorable pre-layout snapshot rather than rolling back more than the layout.\n4. **Without `before_id` (late undo):** compare `.data[0]` to the current graph. If they\n   match, restore `.data[1].id` **only if it exists** — and only when you know `.data[0]` was\n   already the current snapshot before the last edit (usual linear history). If `.data[1]` is\n   missing, report no restorable pre-edit state. If they do **not** match, walk the list for\n   a row that matches the current graph. If an **older** row matches (post-restore), restore\n   **that** id — not `.data[1]`, which can roll the workflow forward. If **no** row matches,\n   the post-edit snapshot has not landed (fire-and-forget lag): poll `list` a few times. If\n   `.data[0]` then matches, follow the match case above. If still none, restore `.data[0]`\n   (still the pre-edit graph in linear history). Do not look for a snapshot of the current\n   unsnapshotted graph — it cannot exist until that async row lands. Do not pass a null\n   snapshot id to `restore`.\n\nTo undo multiple edits, pick an older snapshot id from the list instead.\n\nRemember: this only rolls back the draft. Live automation (if already published)\nkeeps running the previously published version until the user publishes again.\n\n### Compare current state to a previous version\n\nList snapshots, then diff two of them with the `jq` recipe above.\n\n### Review what a run executed\n\nSince runs are pegged to snapshots, inspect the exact workflow state a run used by\nlooking up the run's snapshot id and passing it to `snapshots get`.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}