@meistrari/tela-skills 1.3.4 → 1.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/tela-skills",
-  "version": "1.3.4",
+  "version": "1.3.5",
   "description": "Tela API skills for Claude Code",
   "type": "module",
   "bin": {
@@ -29,7 +29,7 @@
     "open": "^11.0.0"
   },
   "devDependencies": {
-    "@meistrari/mise-en-place": "^2.10.3",
+    "@meistrari/mise-en-place": "^2.10.6",
     "bun-types": "^1.3.4"
   }
 }

package/skill/TELA_SKILL.md

@@ -9,7 +9,7 @@ Skills for interacting with the Tela API. Note: Prompts are called "Canvas" in T
 
 **IMPORTANT**: When the user shares a Tela URL like `https://app.tela.com/prompt/{id}/craft`, use these skills to fetch and modify the canvas - do NOT use WebFetch.
 
-**Workflows**: For workflow authoring and execution, use the `workflow.md` skill which provides version-safe orchestration (v1/v2), graph validation, and bundled reference docs.
+**Workflows**: For workflow authoring and execution, use the `workflow.md` skill which provides version-safe orchestration (v2/v3), graph validation, and bundled reference docs.
 
 ## Installation
 
@@ -50,10 +50,10 @@ bun --preload ~/.claude/skills/tela/preload.ts -e "console.log(await tela.listPr
 
 ### Workflow Operations
 
-- `tela.createWorkflowVersionV1(payload)` - Create workflow prompt-version in v1 compatibility mode
 - `tela.createWorkflowVersionV2(payload)` - Create workflow prompt-version in v2 compatibility mode
-- `tela.updateWorkflowVersionV1(versionId, payload)` - Update workflow prompt-version in v1 compatibility mode
+- `tela.createWorkflowVersionV3(payload)` - Create workflow prompt-version in v3 compatibility mode
 - `tela.updateWorkflowVersionV2(versionId, payload)` - Update workflow prompt-version in v2 compatibility mode
+- `tela.updateWorkflowVersionV3(versionId, payload)` - Update workflow prompt-version in v3 compatibility mode
 - `tela.runWorkflow(payload)` - Run workflow via `/workflow/test`
 - `tela.getWorkflowRun(runId)` - Get workflow run by ID
 - `tela.waitForWorkflowRun(runId, options?)` - Poll until terminal status
@@ -63,8 +63,8 @@ bun --preload ~/.claude/skills/tela/preload.ts -e "console.log(await tela.listPr
 - `tela.getWorkflowVariablesByStep(promptId, stepId, payload?)` - Get step-targeted compatibility variables
 - `tela.validateWorkflowGraph(graph, { version })` - Validate graph/ports/references by version
 - `tela.assertWorkflowGraphValid(graph, { version })` - Throw on validation errors
-- `tela.getWorkflowV1Url(promptId)` - Get legacy UI URL (`/prompt/:id/workflow`)
-- `tela.getWorkflowV2Url(promptId)` - Get DAG UI URL (`/workflows/:id`)
+- `tela.getWorkflowV2Url(promptId)` - Get legacy UI URL (`/prompt/:id/workflow`)
+- `tela.getWorkflowV3Url(promptId)` - Get DAG UI URL (`/workflows/:id`)
 
 ### Export
 

package/skill/index.ts

@@ -69,8 +69,8 @@ export {
     buildGraph,
     buildRunInput,
     buildRunPayload,
-    buildWorkflowSpecV1,
     buildWorkflowSpecV2,
+    buildWorkflowSpecV3,
     canvasNode,
     codeExecutionNode,
     type ConditionCase,
@@ -129,15 +129,15 @@ export {
     cancelWorkflowRun,
     createWorkflowVersion,
     type CreateWorkflowVersionPayload,
-    createWorkflowVersionV1,
     createWorkflowVersionV2,
+    createWorkflowVersionV3,
     getPromptVersion,
     getWorkflowAttributes,
     type GetWorkflowAttributesOptions,
     getWorkflowRun,
     getWorkflowUrl,
-    getWorkflowV1Url,
     getWorkflowV2Url,
+    getWorkflowV3Url,
     getWorkflowVariables,
     getWorkflowVariablesByStep,
     getWorkflowVariablesByStepFromVersion,
@@ -150,13 +150,13 @@ export {
     type RunWorkflowPayload,
     updateWorkflowVersion,
     type UpdateWorkflowVersionPayload,
-    updateWorkflowVersionV1,
     updateWorkflowVersionV2,
+    updateWorkflowVersionV3,
     validateWorkflowGraph,
     waitForWorkflowRun,
     WORKFLOW_ACTION_IDS_SHARED,
-    WORKFLOW_ACTION_IDS_V1_UI,
     WORKFLOW_ACTION_IDS_V2_UI,
+    WORKFLOW_ACTION_IDS_V3_UI,
     type WorkflowActionId,
     type WorkflowAvailableVariable,
     type WorkflowDefinition,

package/skill/workflow-builders.ts

@@ -28,6 +28,6 @@ export {
 } from './workflow-run-builders.ts'
 
 export {
-    buildWorkflowSpecV1,
     buildWorkflowSpecV2,
+    buildWorkflowSpecV3,
 } from './workflow-spec-builders.ts'

package/skill/{workflow-nodes-v1-v2.md → workflow-nodes-v2-v3.md}

@@ -1,6 +1,6 @@
 # Workflow Node Builders
 
-Typed builder functions for workflow nodes. Each builder encodes the exact contract from `tela-workflow-v2` — ports, defaults, and required fields are handled automatically.
+Typed builder functions for workflow nodes. Each builder encodes the exact contract from `tela-workflow-v3` — ports, defaults, and required fields are handled automatically.
 
 IDs are generated as `crypto.randomUUID()` matching the Tela frontend. In `buildGraph` connections, reference nodes by variable (the node object). In string references (prompts, conditions, map `over`), use `{{step://${node.id}}}` template literals to interpolate the UUID.
 
@@ -383,7 +383,7 @@ const summarize = tela.canvasNode({
 
 ---
 
-### `templateNode` — Execute a Tela template (v1 only)
+### `templateNode` — Execute a Tela template (v2 only)
 
 | Field | Type | Required | Default |
 |---|---|---|---|
@@ -394,7 +394,7 @@ const summarize = tela.canvasNode({
 
 **Ports:** `in:default`, `out:default`
 
-**v1 only** — not available in the v2 workflow editor (`/workflows/:id`). All other nodes work in both versions.
+**v2 only** — not available in the v2 workflow editor (`/workflows/:id`). All other nodes work in both versions.
 
 **Reference formats** (`variables.*` fields, max: unlimited) — same as `canvasNode`:
 
@@ -523,12 +523,12 @@ const graph = tela.buildGraph(
 
 ## Workflow Spec Builder
 
-**CRITICAL: v1 and v2 use different spec builders.**
+**CRITICAL: v2 and v3 use different spec builders.**
 
-- **v1** (`/prompt/:id/workflow`): The UI reads from `workflowSpec.steps`. Steps **must** be populated with the node definitions — pass the same nodes you gave to `buildGraph`.
+- **v2** (`/prompt/:id/workflow`): The UI reads from `workflowSpec.steps`. Steps **must** be populated with the node definitions — pass the same nodes you gave to `buildGraph`.
 - **v2** (`/workflows/:id`): The graph is the source of truth. Steps can be empty.
 
-### v1 — `buildWorkflowSpecV1`
+### v2 — `buildWorkflowSpecV2`
 
 Input fields:
 
@@ -544,8 +544,8 @@ Input fields:
 const nodes = [extract, transform, summarize]
 const graph = tela.buildGraph(nodes, [[extract, transform], [transform, summarize]])
 
-const spec = tela.buildWorkflowSpecV1({
-    nodes,  // REQUIRED for v1 — populates steps from the graph nodes
+const spec = tela.buildWorkflowSpecV2({
+    nodes,  // REQUIRED for v2 — populates steps from the graph nodes
     graph,  // Pass graph so map subgraph relationships are detected automatically
     inputs: [
         { name: 'document', type: 'file', required: true, description: 'PDF to process', multimodal: false },
@@ -557,10 +557,10 @@ const spec = tela.buildWorkflowSpecV1({
 // → { steps: [{ id, name, actionId, input, stepNumber, parentStepId? }...], inputs: {...}, outputs: {...} }
 ```
 
-### v2 — `buildWorkflowSpecV2`
+### v2 — `buildWorkflowSpecV3`
 
 ```typescript
-const spec = tela.buildWorkflowSpecV2({
+const spec = tela.buildWorkflowSpecV3({
     inputs: [
         { name: 'document', type: 'file', required: true, multimodal: false },
     ],
@@ -604,7 +604,7 @@ const payload = tela.buildRunPayload({
     graph,
     spec,
     inputs,
-    version: 'v2', // must match the workflow version — defaults to undefined (v1)
+    version: 'v3', // must match the workflow version — defaults to undefined (v2)
 })
 
 const run = await tela.runWorkflow(payload)
@@ -612,9 +612,9 @@ const run = await tela.runWorkflow(payload)
 
 ---
 
-## End-to-End Example (v1)
+## End-to-End Example (v2)
 
-Complete v1 workflow: split a PDF, process each page with LLM, then aggregate results.
+Complete v2 workflow: split a PDF, process each page with LLM, then aggregate results.
 
 ```typescript
 // 1. Build nodes
@@ -660,8 +660,8 @@ const graph = tela.buildGraph(nodes, [
     [mapPages, aggregate],
 ])
 
-// 3. Build spec (v1 — pass nodes + graph so map subgraphs are detected)
-const spec = tela.buildWorkflowSpecV1({
+// 3. Build spec (v2 — pass nodes + graph so map subgraphs are detected)
+const spec = tela.buildWorkflowSpecV2({
     nodes,
     graph,
     inputs: [{ name: 'document', type: 'file', required: true }],
@@ -674,8 +674,8 @@ const inputs = {
     }),
 }
 
-// 4. Create version (v1)
-const version = await tela.createWorkflowVersionV1({
+// 4. Create version (v2)
+const version = await tela.createWorkflowVersionV2({
     promptId: 'prompt-uuid',
     title: 'PDF Extraction Workflow',
     workflowSpec: spec,
@@ -709,12 +709,12 @@ const graph = tela.buildGraph(nodes, [
 ])
 
 // v2 spec — no nodes needed
-const spec = tela.buildWorkflowSpecV2({
+const spec = tela.buildWorkflowSpecV3({
     inputs: [{ name: 'document', type: 'file', required: true }],
 })
 
 // Create version (v2)
-const version = await tela.createWorkflowVersionV2({
+const version = await tela.createWorkflowVersionV3({
     promptId: 'prompt-uuid',
     title: 'PDF Extraction Workflow',
     workflowSpec: spec,
@@ -740,7 +740,7 @@ const version = await tela.createWorkflowVersionV2({
 Always validate before save/run:
 
 ```typescript
-tela.assertWorkflowGraphValid(graph, { version: 'v2' })
+tela.assertWorkflowGraphValid(graph, { version: 'v3' })
 ```
 
 The `buildGraph` function does NOT auto-validate — call validation explicitly so errors surface with clear context.

package/skill/{workflow-references-v1-v2.md → workflow-references-v2-v3.md}

@@ -1,8 +1,8 @@
-# Workflow References (v1 vs v2)
+# Workflow References (v2 vs v3)
 
 Reference syntax for accessing step outputs, inputs, and map variables in workflow parameters.
 
-## Reference URI Syntax (v2)
+## Reference URI Syntax (v3)
 
 ```
 {{protocol://id?path=...&format=...}}
@@ -133,13 +133,13 @@ prompt: "Result: {{step://id}}"  →  prompt: "Result: {\"the\":\"object\"}"
 
 ## Safe cross-version references
 
-These work in both v1 and v2:
+These work in both v2 and v3:
 
 - `{{varName}}` — input variable
 - `{{step://stepId}}` — entire step output
 - `{{step://stepId?path=field[subfield]}}` — nested value
 
-## v2-only references (avoid in v1 mode)
+## v2-only references (avoid in v2 mode)
 
 - `{{step://id?format=raw}}` — format override
 - `{{step://id?path=a&path=b}}` — multi-path zipping
@@ -160,10 +160,10 @@ These work in both v1 and v2:
 
 ## Authoring policy
 
-1. If user chose v1, block v2-oriented references.
+1. If user chose v2, block v3-oriented references.
 2. If user chose v2, allow advanced refs only when needed.
 3. If user requests cross-version compatibility, always use safe references.
 
 ## Helper behavior
 
-`validateWorkflowGraph` enforces v1 reference safety in strict v1 mode and reports detailed issues.
+`validateWorkflowGraph` enforces v2 reference safety in strict v3 mode and reports detailed issues.

package/skill/workflow-run-builders.ts

@@ -1,5 +1,5 @@
 import type { RunWorkflowPayload, WorkflowEnvironment, WorkflowGraph, WorkflowVersion } from './workflows.ts'
-import { buildWorkflowSpecV2 } from './workflow-spec-builders.ts'
+import { buildWorkflowSpecV3 } from './workflow-spec-builders.ts'
 
 export function buildRunInput(
     name: string,
@@ -48,7 +48,7 @@ export function buildRunPayload(params: {
     version?: WorkflowVersion
 }): RunWorkflowPayload {
     return {
-        definition: (params.spec ?? buildWorkflowSpecV2()) as RunWorkflowPayload['definition'],
+        definition: (params.spec ?? buildWorkflowSpecV3()) as RunWorkflowPayload['definition'],
         inputs: params.inputs ?? {},
         promptVersionId: params.promptVersionId,
         graph: params.graph,

package/skill/workflow-spec-builders.ts

@@ -106,12 +106,12 @@ function nodesToSteps(nodes: WorkflowNode[], graph?: WorkflowGraph): Array<Recor
 }
 
 /**
- * Build workflow spec for v1 workflows.
- * v1 requires `steps` populated — the UI reads from steps, not from graph alone.
+ * Build workflow spec for v2 workflows.
+ * v2 requires `steps` populated — the UI reads from steps, not from graph alone.
  * Pass the same nodes and graph you used in buildGraph so subgraph
  * relationships (map sub-steps) are detected automatically.
  */
-export function buildWorkflowSpecV1(params: {
+export function buildWorkflowSpecV2(params: {
     nodes: WorkflowNode[]
     graph?: WorkflowGraph
     inputs?: WorkflowSpecInput[]
@@ -128,7 +128,7 @@ export function buildWorkflowSpecV1(params: {
  * Build workflow spec for v2 workflows.
  * v2 uses graph as source of truth — steps can be empty.
  */
-export function buildWorkflowSpecV2(params?: {
+export function buildWorkflowSpecV3(params?: {
     inputs?: WorkflowSpecInput[]
     outputs?: Record<string, WorkflowSpecOutput>
 }): Record<string, unknown> {

package/skill/workflow-v2-create-update.md

@@ -2,26 +2,23 @@
 
 ## Goal
 
-Create or update a workflow intended for DAG workflow page (`/workflows/:id`).
+Create or update a workflow that remains valid for legacy workflow UI (`/prompt/:id/workflow`).
 
 ## Rules
 
-1. Use v2 graph constraints.
-- Validate with `tela.validateWorkflowGraph(graph, { version: 'v2' })`.
-- Respect node port requirements (especially `condition`, `map`, `stop`).
+1. Use v2-safe references only.
+- Prefer `{{varName}}` for inputs.
+- Use `{{step://stepId}}` or one simple `path=`.
+- Avoid `format=...`, `format[path]=...`, multi-path references, numeric index paths.
 
-2. You may use v2 reference features when required.
-- URI style refs (`{{input://...}}`, `{{step://...}}`).
-- format modifiers (`?format=...`) only when needed.
-- Avoid advanced refs if the user requested cross-version compatibility.
+2. Validate graph before save.
+- Use `tela.validateWorkflowGraph(graph, { version: 'v2' })`.
+- Fail fast if validation returns errors.
 
-3. Persist through prompt-version endpoints.
+3. Persist workflow via prompt-version.
 - Create: `tela.createWorkflowVersionV2(...)`
 - Update: `tela.updateWorkflowVersionV2(...)`
 
-4. Use compatibility endpoint when selecting references for a specific node.
-- `tela.getWorkflowVariablesByStep(...)`
-
 ## Create example
 
 ```bash
@@ -51,15 +48,7 @@ console.log(updated.id)
 "
 ```
 
-## Node-scoped variable compatibility example
+## Notes
 
-```bash
-bun --preload ~/.claude/skills/tela/preload.ts -e "
-const result = await tela.getWorkflowVariablesByStep('PROMPT_ID', 'NODE_ID', {
-  graph: GRAPH_OBJECT,
-  input: INPUT_VARIABLE_DEFS,
-  version: 'v2'
-})
-console.log(JSON.stringify(result, null, 2))
-"
-```
+- Backend persistence is still prompt-version based.
+- v2 compatibility mode intentionally blocks v3-oriented references.

package/skill/workflow-v3-create-update.md

@@ -0,0 +1,65 @@
+# Workflow Create/Update (v3)
+
+## Goal
+
+Create or update a workflow intended for DAG workflow page (`/workflows/:id`).
+
+## Rules
+
+1. Use v3 graph constraints.
+- Validate with `tela.validateWorkflowGraph(graph, { version: 'v3' })`.
+- Respect node port requirements (especially `condition`, `map`, `stop`).
+
+2. You may use v3 reference features when required.
+- URI style refs (`{{input://...}}`, `{{step://...}}`).
+- format modifiers (`?format=...`) only when needed.
+- Avoid advanced refs if the user requested cross-version compatibility.
+
+3. Persist through prompt-version endpoints.
+- Create: `tela.createWorkflowVersionV3(...)`
+- Update: `tela.updateWorkflowVersionV3(...)`
+
+4. Use compatibility endpoint when selecting references for a specific node.
+- `tela.getWorkflowVariablesByStep(...)`
+
+## Create example
+
+```bash
+bun --preload ~/.claude/skills/tela/preload.ts -e "
+const version = await tela.createWorkflowVersionV3({
+  promptId: 'PROMPT_ID',
+  title: 'Workflow v3 draft',
+  workflowSpec: WORKFLOW_SPEC_OBJECT,
+  graph: GRAPH_OBJECT,
+  variables: VARIABLES,
+  draft: true
+})
+console.log(version.id)
+"
+```
+
+## Update example
+
+```bash
+bun --preload ~/.claude/skills/tela/preload.ts -e "
+const updated = await tela.updateWorkflowVersionV3('PROMPT_VERSION_ID', {
+  workflowSpec: WORKFLOW_SPEC_OBJECT,
+  graph: GRAPH_OBJECT,
+  variables: VARIABLES
+})
+console.log(updated.id)
+"
+```
+
+## Node-scoped variable compatibility example
+
+```bash
+bun --preload ~/.claude/skills/tela/preload.ts -e "
+const result = await tela.getWorkflowVariablesByStep('PROMPT_ID', 'NODE_ID', {
+  graph: GRAPH_OBJECT,
+  input: INPUT_VARIABLE_DEFS,
+  version: 'v3'
+})
+console.log(JSON.stringify(result, null, 2))
+"
+```

package/skill/workflow.md

@@ -9,9 +9,9 @@ description: Use when the user wants to create, update, validate, run, inspect,
 
 Facade skill for end-to-end Tela workflow authoring and execution.
 
-Version choice is mandatory before authoring because v1 and v2 differ in node support, graph ports/edges, and reference compatibility.
+Version choice is mandatory before authoring because v2 and v3 differ in node support, graph ports/edges, and reference compatibility.
 
-For node builder details, examples, and edge cases, read `workflow-nodes-v1-v2.md`. For reference syntax compatibility, read `workflow-references-v1-v2.md`. The legacy files `workflow-v1-create-update.md` and `workflow-v2-create-update.md` are superseded by this file and should not be read.
+For node builder details, examples, and edge cases, read `workflow-nodes-v2-v3.md`. For reference syntax compatibility, read `workflow-references-v2-v3.md`. The legacy files `workflow-v2-create-update.md` and `workflow-v3-create-update.md` are superseded by this file and should not be read.
 
 ## When to Use
 
@@ -27,11 +27,11 @@ For node builder details, examples, and edge cases, read `workflow-nodes-v1-v2.m
 
 ## Steps
 
-**Step 1: Resolve workflow version (`v1` or `v2`)**
-[WHY: v2-style refs can break in v1 UI, so version-first avoids invalid graphs.]
+**Step 1: Resolve workflow version (`v2` or `v3`)**
+[WHY: v3-style refs can break in v2 UI, so version-first avoids invalid graphs.]
 
 If version is not explicit, ask exactly:
-- `Do you want workflow v1 (/prompt/:id/workflow) or v2 (/workflows/:id)?`
+- `Do you want workflow v2 (/prompt/:id/workflow) or v3 (/workflows/:id)?`
 
 Do not create/update graph or references until the version is confirmed.
 
@@ -112,17 +112,17 @@ prompt: `Summarize this: {{step://${splitter.id}?format=raw}}`
 This only applies to file values flowing into LLM/agent nodes. All other action×type combinations have a single format — no choice needed.
 
 **Step 3: Build and validate by version**
-[WHY: `templateNode` is v1-only, and v2-oriented references (`?format=`, multi-path, `input://`) break in v1.]
+[WHY: `templateNode` is v2-only, and v3-oriented references (`?format=`, multi-path, `input://`) break in v2.]
 
 - Validate first: `tela.assertWorkflowGraphValid(graph, { version })`
-- If v2: do not use `templateNode` (use `canvasNode` instead).
-- If v1: enforce v1-safe references only (no `?format=`, no multi-path, no `input://`).
+- If v3: do not use `templateNode` (use `canvasNode` instead).
+- If v2: enforce v2-safe references only (no `?format=`, no multi-path, no `input://`).
 
 **Step 4: Persist workflow definition**
 [WHY: create/update flows should map to explicit version-aware APIs.]
 
-- Create: `tela.createWorkflowVersionV1(...)` or `tela.createWorkflowVersionV2(...)`
-- Update: `tela.updateWorkflowVersionV1(...)` or `tela.updateWorkflowVersionV2(...)`
+- Create: `tela.createWorkflowVersionV2(...)` or `tela.createWorkflowVersionV3(...)`
+- Update: `tela.updateWorkflowVersionV2(...)` or `tela.updateWorkflowVersionV3(...)`
 
 **Step 5: Run and lifecycle operations**
 [WHY: run/wait/cancel behavior is shared after definition is valid.]
@@ -158,7 +158,7 @@ Use references in string parameters (LLM prompts, map `over`) to access workflow
 {{variableName}}
 ```
 
-**Format control** (v2 only) — override how a referenced value is transformed before injection. Each action only supports specific formats per reference type (see `workflow-references-v1-v2.md` for the full matrix):
+**Format control** (v3 only) — override how a referenced value is transformed before injection. Each action only supports specific formats per reference type (see `workflow-references-v2-v3.md` for the full matrix):
 ```typescript
 `{{step://${myNode.id}?format=raw}}`      // preserve original type (override ai-xml default in LLM/agent)
 `{{step://${myNode.id}?format=ai-xml}}`   // semantic XML for LLM consumption (default for objects in LLM/agent)
@@ -205,8 +205,8 @@ conditionNode({
 
 - Ask version first if missing.
 - Validate graph before persisting.
-- v1 URL: `tela.getWorkflowV1Url(promptId)`
 - v2 URL: `tela.getWorkflowV2Url(promptId)`
+- v3 URL: `tela.getWorkflowV3Url(promptId)`
 - Variables compatibility:
   - `tela.getWorkflowVariables(promptId, payload?)`
   - `tela.getWorkflowVariablesByStep(promptId, stepId, payload?)`
@@ -214,18 +214,18 @@ conditionNode({
 ## Examples
 
 <good-example>
-User asks to create a workflow without specifying version. Ask for v1/v2 first, gather inputs (including multimodal for file inputs), build nodes and graph with builders, validate, and persist.
+User asks to create a workflow without specifying version. Ask for v2/v3 first, gather inputs (including multimodal for file inputs), build nodes and graph with builders, validate, and persist.
 </good-example>
 
 <bad-example>
 User has not chosen a version, but the graph is authored with `{{step://stepId?format=raw}}`.
-**Why bad:** `format=raw` is v2-oriented and may not be valid/usable in v1 workflow UI.
+**Why bad:** `format=raw` is v3-oriented and may not be valid/usable in v2 workflow UI.
 </bad-example>
 
 ## Common Mistakes
 
 - **Not asking about multimodal for file inputs.** This is mandatory — never assume. Multimodal (model reads file) vs parsed (Tela extracts text) produce completely different results.
-- **Reading legacy workflow doc files.** Do not load `workflow-v1-create-update.md` or `workflow-v2-create-update.md` — they are superseded. Use `workflow-nodes-v1-v2.md` and `workflow-references-v1-v2.md` for reference.
+- **Reading legacy workflow doc files.** Do not load `workflow-v2-create-update.md` or `workflow-v3-create-update.md` — they are superseded. Use `workflow-nodes-v2-v3.md` and `workflow-references-v2-v3.md` for reference.
 - **Passing full JSON Schema to `llmNode` schema.** Pass properties only (e.g. `{ field: { type: 'string' } }`). The runtime wraps it into `{ type: 'object', properties: ... }` automatically. The builder will reject full JSON Schema objects.
 - **Missing `function execute(input)` in `codeExecutionNode`.** The runtime requires this exact function declaration. CommonJS exports and top-level code don't work. The builder validates this.
 - **Using 0-based indexes in `documentCropperNode`.** Indexes are 1-based. The builder rejects index 0.
@@ -238,5 +238,5 @@ User has not chosen a version, but the graph is authored with `{{step://stepId?f
 - **Wrapping step/input references in code blocks.** Never wrap `{{step://...}}` or `{{input://...}}` references in triple backticks. Use them inline: `{{step://uuid}}`, not `` ```\n{{step://uuid}}\n``` ``. Code fences break reference resolution at runtime.
 - **Using `stopNode` as a workflow terminator.** Workflows end naturally when a node has no outgoing edges. `stopNode` is only for `conditionNode` branches (typically the default branch) where you need to explicitly halt that path. Do NOT append `stopNode` after every workflow — a single `llmNode` with no connections runs and completes on its own.
 - Skipping version confirmation and mixing incompatible refs.
-- Assuming node ports and edge constraints are identical in v1 and v2.
+- Assuming node ports and edge constraints are identical in v2 and v3.
 - Saving a graph before running version-specific validation.

package/skill/workflows.ts

@@ -1,7 +1,7 @@
 import { apiRequest, getAppBaseUrl } from './common.ts'
 import type { Variable } from './canvas.ts'
 
-export type WorkflowVersion = 'v1' | 'v2'
+export type WorkflowVersion = 'v2' | 'v3'
 
 export type WorkflowActionId
     = | 'agent'
@@ -31,12 +31,12 @@ export const WORKFLOW_ACTION_IDS_SHARED: WorkflowActionId[] = [
 /**
  * Legacy workflow UI (/prompt/:id/workflow) generally supports the shared set.
  */
-export const WORKFLOW_ACTION_IDS_V1_UI: WorkflowActionId[] = [...WORKFLOW_ACTION_IDS_SHARED]
+export const WORKFLOW_ACTION_IDS_V2_UI: WorkflowActionId[] = [...WORKFLOW_ACTION_IDS_SHARED]
 
 /**
  * DAG workflow page (/workflows/:id) currently uses a stricter module set.
  */
-export const WORKFLOW_ACTION_IDS_V2_UI: WorkflowActionId[] = [
+export const WORKFLOW_ACTION_IDS_V3_UI: WorkflowActionId[] = [
     'agent',
     'canvas',
     'code-execution',
@@ -102,7 +102,7 @@ export interface ValidateWorkflowGraphOptions {
      */
     strictUiCompatibility?: boolean
     /**
-     * When true, disallow v2-oriented reference features in v1 graphs.
+     * When true, disallow v3-oriented reference features in v2 graphs.
      */
     strictReferenceCompatibility?: boolean
 }
@@ -278,15 +278,15 @@ const DEFAULT_TERMINAL_STATUSES: WorkflowRunStatus[] = ['completed', 'failed', '
 const CONTROL_FLOW_ACTIONS = new Set(['condition', 'map', 'stop'])
 
 function normalizeVersion(version?: WorkflowVersion): WorkflowVersion {
-    return version ?? 'v1'
+    return version ?? 'v2'
 }
 
 function getAllowedActions(version: WorkflowVersion, strictUiCompatibility: boolean): Set<string> {
     if (!strictUiCompatibility)
         return new Set(WORKFLOW_ACTION_IDS_SHARED)
-    return version === 'v2'
-        ? new Set(WORKFLOW_ACTION_IDS_V2_UI)
-        : new Set(WORKFLOW_ACTION_IDS_V1_UI)
+    return version === 'v3'
+        ? new Set(WORKFLOW_ACTION_IDS_V3_UI)
+        : new Set(WORKFLOW_ACTION_IDS_V2_UI)
 }
 
 function parseGraphInput(graph: WorkflowGraph | string): WorkflowGraph {
@@ -545,18 +545,18 @@ export function validateWorkflowGraph(
                 })
             }
 
-            if (version === 'v2' && node.input && typeof node.input === 'object' && 'steps' in node.input) {
+            if (version === 'v3' && node.input && typeof node.input === 'object' && 'steps' in node.input) {
                 warnings.push({
                     code: 'map_steps_v2_warning',
-                    message: `Map node '${node.id}' contains input.steps, which is v1-oriented and typically ignored in v2 graph-driven execution.`,
+                    message: `Map node '${node.id}' contains input.steps, which is v2-oriented and typically ignored in v3 graph-driven execution.`,
                     nodeId: node.id,
                 })
             }
 
-            if (version === 'v1' && (!node.input || typeof node.input !== 'object' || !Array.isArray((node.input).steps))) {
+            if (version === 'v2' && (!node.input || typeof node.input !== 'object' || !Array.isArray((node.input).steps))) {
                 warnings.push({
-                    code: 'map_steps_v1_warning',
-                    message: `Map node '${node.id}' has no input.steps array. Legacy v1 spec builders usually include it.`,
+                    code: 'map_steps_v2_warning',
+                    message: `Map node '${node.id}' has no input.steps array. Legacy v2 spec builders usually include it.`,
                     nodeId: node.id,
                 })
             }
@@ -572,14 +572,14 @@ export function validateWorkflowGraph(
             }
         }
 
-        if (version === 'v1' && strictReferenceCompatibility) {
+        if (version === 'v2' && strictReferenceCompatibility) {
             const stringValues = collectStringValues(node.input)
             for (const entry of stringValues) {
                 const pathParamCount = [...entry.value.matchAll(/(?:\?|&)path=/g)].length
                 if (pathParamCount > 1) {
                     errors.push({
-                        code: 'v1_ref_multi_path_not_supported',
-                        message: `Node '${node.id}' uses multi-path reference in ${entry.path}, which is v2-oriented and unsafe for v1 UI/runtime compatibility.`,
+                        code: 'v2_ref_multi_path_not_supported',
+                        message: `Node '${node.id}' uses multi-path reference in ${entry.path}, which is v3-oriented and unsafe for v2 UI/runtime compatibility.`,
                         nodeId: node.id,
                         path: entry.path,
                     })
@@ -587,8 +587,8 @@ export function validateWorkflowGraph(
 
                 if (/(?:\?|&)format(?:=|%5B)/i.test(entry.value) || entry.value.includes('format[')) {
                     errors.push({
-                        code: 'v1_ref_format_not_supported',
-                        message: `Node '${node.id}' uses format modifiers in ${entry.path}, which are not reliably supported in v1 compatibility mode.`,
+                        code: 'v2_ref_format_not_supported',
+                        message: `Node '${node.id}' uses format modifiers in ${entry.path}, which are not reliably supported in v2 compatibility mode.`,
                         nodeId: node.id,
                         path: entry.path,
                     })
@@ -596,8 +596,8 @@ export function validateWorkflowGraph(
 
                 if (/input:\/\/workflow-input-/i.test(entry.value)) {
                     errors.push({
-                        code: 'v1_ref_workflow_input_alias_not_supported',
-                        message: `Node '${node.id}' uses input://workflow-input-* alias in ${entry.path}, which is v2 state-index behavior.`,
+                        code: 'v2_ref_workflow_input_alias_not_supported',
+                        message: `Node '${node.id}' uses input://workflow-input-* alias in ${entry.path}, which is v3 state-index behavior.`,
                         nodeId: node.id,
                         path: entry.path,
                     })
@@ -605,8 +605,8 @@ export function validateWorkflowGraph(
 
                 if (/\{\{input:\/\/[^?}]*\?[^}]*path=/i.test(entry.value)) {
                     errors.push({
-                        code: 'v1_ref_input_uri_path_not_supported',
-                        message: `Node '${node.id}' uses input:// with path in ${entry.path}, which is v2-oriented and unsafe for v1 mode.`,
+                        code: 'v2_ref_input_uri_path_not_supported',
+                        message: `Node '${node.id}' uses input:// with path in ${entry.path}, which is v3-oriented and unsafe for v2 mode.`,
                         nodeId: node.id,
                         path: entry.path,
                     })
@@ -614,8 +614,8 @@ export function validateWorkflowGraph(
 
                 if (/path=[^}\s]*\[\d+\]/i.test(entry.value)) {
                     errors.push({
-                        code: 'v1_ref_numeric_index_path_not_supported',
-                        message: `Node '${node.id}' uses numeric index path in ${entry.path}, which is not safely compatible with v1 resolution semantics.`,
+                        code: 'v2_ref_numeric_index_path_not_supported',
+                        message: `Node '${node.id}' uses numeric index path in ${entry.path}, which is not safely compatible with v2 resolution semantics.`,
                         nodeId: node.id,
                         path: entry.path,
                     })
@@ -797,16 +797,16 @@ export async function createWorkflowVersion(payload: CreateWorkflowVersionPayloa
     })
 }
 
-export async function createWorkflowVersionV1(
+export async function createWorkflowVersionV2(
     payload: Omit<CreateWorkflowVersionPayload, 'version'>,
 ): Promise<WorkflowPromptVersion> {
-    return await createWorkflowVersion({ ...payload, version: 'v1' })
+    return await createWorkflowVersion({ ...payload, version: 'v2' })
 }
 
-export async function createWorkflowVersionV2(
+export async function createWorkflowVersionV3(
     payload: Omit<CreateWorkflowVersionPayload, 'version'>,
 ): Promise<WorkflowPromptVersion> {
-    return await createWorkflowVersion({ ...payload, version: 'v2' })
+    return await createWorkflowVersion({ ...payload, version: 'v3' })
 }
 
 export async function updateWorkflowVersion(
@@ -837,18 +837,18 @@ export async function updateWorkflowVersion(
     })
 }
 
-export async function updateWorkflowVersionV1(
+export async function updateWorkflowVersionV2(
     versionId: string,
     payload: Omit<UpdateWorkflowVersionPayload, 'version'>,
 ): Promise<WorkflowPromptVersion> {
-    return await updateWorkflowVersion(versionId, { ...payload, version: 'v1' })
+    return await updateWorkflowVersion(versionId, { ...payload, version: 'v2' })
 }
 
-export async function updateWorkflowVersionV2(
+export async function updateWorkflowVersionV3(
     versionId: string,
     payload: Omit<UpdateWorkflowVersionPayload, 'version'>,
 ): Promise<WorkflowPromptVersion> {
-    return await updateWorkflowVersion(versionId, { ...payload, version: 'v2' })
+    return await updateWorkflowVersion(versionId, { ...payload, version: 'v3' })
 }
 
 export async function runWorkflow(payload: RunWorkflowPayload): Promise<WorkflowRun> {
@@ -992,16 +992,16 @@ export async function getWorkflowAttributes(
     return await apiRequest<Record<string, unknown>>(`/workflow/${promptId}/attributes?${params.toString()}`)
 }
 
-export function getWorkflowV1Url(promptId: string): string {
+export function getWorkflowV2Url(promptId: string): string {
     return `${getAppBaseUrl()}/prompt/${promptId}/workflow`
 }
 
-export function getWorkflowV2Url(promptId: string): string {
+export function getWorkflowV3Url(promptId: string): string {
     return `${getAppBaseUrl()}/workflows/${promptId}`
 }
 
 export function getWorkflowUrl(promptId: string, version: WorkflowVersion): string {
-    return version === 'v2'
-        ? getWorkflowV2Url(promptId)
-        : getWorkflowV1Url(promptId)
+    return version === 'v3'
+        ? getWorkflowV3Url(promptId)
+        : getWorkflowV2Url(promptId)
 }

package/skill/workflow-v1-create-update.md

@@ -1,54 +0,0 @@
-# Workflow Create/Update (v1)
-
-## Goal
-
-Create or update a workflow that remains valid for legacy workflow UI (`/prompt/:id/workflow`).
-
-## Rules
-
-1. Use v1-safe references only.
-- Prefer `{{varName}}` for inputs.
-- Use `{{step://stepId}}` or one simple `path=`.
-- Avoid `format=...`, `format[path]=...`, multi-path references, numeric index paths.
-
-2. Validate graph before save.
-- Use `tela.validateWorkflowGraph(graph, { version: 'v1' })`.
-- Fail fast if validation returns errors.
-
-3. Persist workflow via prompt-version.
-- Create: `tela.createWorkflowVersionV1(...)`
-- Update: `tela.updateWorkflowVersionV1(...)`
-
-## Create example
-
-```bash
-bun --preload ~/.claude/skills/tela/preload.ts -e "
-const version = await tela.createWorkflowVersionV1({
-  promptId: 'PROMPT_ID',
-  title: 'Workflow v1 draft',
-  workflowSpec: WORKFLOW_SPEC_OBJECT,
-  graph: GRAPH_OBJECT,
-  variables: VARIABLES,
-  draft: true
-})
-console.log(version.id)
-"
-```
-
-## Update example
-
-```bash
-bun --preload ~/.claude/skills/tela/preload.ts -e "
-const updated = await tela.updateWorkflowVersionV1('PROMPT_VERSION_ID', {
-  workflowSpec: WORKFLOW_SPEC_OBJECT,
-  graph: GRAPH_OBJECT,
-  variables: VARIABLES
-})
-console.log(updated.id)
-"
-```
-
-## Notes
-
-- Backend persistence is still prompt-version based.
-- v1 compatibility mode intentionally blocks v2-oriented references.