@vornrun/mcp 0.7.2 → 0.7.3

package/dist/index.js

@@ -3065,6 +3065,10 @@ function registerSessionTools(server) {
 
 // src/tools/workflows.ts
 import crypto4 from "crypto";
+import { isDeepStrictEqual } from "util";
+
+// ../shared/src/template-vars.ts
+var MAX_OUTPUT_LENGTH = 5e4;
 
 // ../shared/src/workflow-graph.ts
 var MAX_GATE_ROUNDS = 10;
@@ -3089,6 +3093,8 @@ function nodesBetween(from, to, edges) {
   const above = reach(to, predecessors);
   return new Set([...below].filter((id) => above.has(id)));
 }
+var LOOP_RESULT_OUTPUT_CHARS = 8e3;
+var MAX_LOOP_ITERATIONS = 10;
 function isSignInWait(state) {
   return state.status === "waiting" && state.waitingFor === "signIn";
 }
@@ -3101,9 +3107,391 @@ function buildGraph(edges) {
   }
   return { successors, predecessors };
 }
+function loopBodyOwners(nodes) {
+  const exists = new Set(nodes.map((n) => n.id));
+  const owners = /* @__PURE__ */ new Map();
+  for (const n of nodes) {
+    if (n.type !== "loop") continue;
+    for (const id of n.config.bodyNodeIds ?? []) {
+      if (exists.has(id) && id !== n.id && !owners.has(id)) owners.set(id, n.id);
+    }
+  }
+  return owners;
+}
+function loopBodyGraph(nodes, edges, loop) {
+  const owners = loopBodyOwners(nodes);
+  const byId = new Map(nodes.map((n) => [n.id, n]));
+  const members = (loop.config.bodyNodeIds ?? []).filter((id) => owners.get(id) === loop.id).map((id) => byId.get(id));
+  const ids = new Set(members.map((m) => m.id));
+  let inner = edges.filter((e) => ids.has(e.source) && ids.has(e.target));
+  if (inner.length === 0 && members.length > 1) {
+    inner = members.slice(1).map((m, i) => ({
+      id: `${members[i].id}->${m.id}:chain`,
+      source: members[i].id,
+      target: m.id
+    }));
+  }
+  const fed = new Set(inner.map((e) => e.target));
+  return { members, edges: inner, entries: members.filter((m) => !fed.has(m.id)).map((m) => m.id) };
+}
+function loopStructureError(nodes, edges, loop) {
+  const { members, edges: inner } = loopBodyGraph(nodes, edges, loop);
+  if (members.length === 0) return "Loop has no body steps. Add at least one step for it to repeat.";
+  const ids = new Set(members.map((m) => m.id));
+  for (const m of members) {
+    if (m.type === "approval") {
+      return `Loop body contains an approval gate ("${m.label}"), which is not supported.`;
+    }
+    if (m.type === "loop")
+      return `Loop body contains another loop ("${m.label}"), which is not supported.`;
+    if (m.type === "trigger") return `Loop body contains a trigger ("${m.label}").`;
+  }
+  for (const e of edges) {
+    if (ids.has(e.target) && !ids.has(e.source) && e.source !== loop.id) {
+      const from = nodes.find((n) => n.id === e.source)?.label ?? e.source;
+      return `"${from}" feeds a step inside the loop from outside it. Only the loop starts its steps.`;
+    }
+    if (ids.has(e.source) && !ids.has(e.target) && e.conditionBranch) {
+      return "A condition inside the loop branches to a step outside it. Keep both branches inside the loop.";
+    }
+  }
+  const indegree = new Map(members.map((m) => [m.id, 0]));
+  for (const e of inner) indegree.set(e.target, (indegree.get(e.target) ?? 0) + 1);
+  const queue = [...indegree].filter(([, d]) => d === 0).map(([id]) => id);
+  let visited = 0;
+  while (queue.length > 0) {
+    const id = queue.shift();
+    visited++;
+    for (const e of inner) {
+      if (e.source !== id) continue;
+      const d = (indegree.get(e.target) ?? 0) - 1;
+      indegree.set(e.target, d);
+      if (d === 0) queue.push(e.target);
+    }
+  }
+  if (visited < members.length) return "The steps inside the loop form a cycle.";
+  return void 0;
+}
 
 // src/tools/workflows.ts
+import { z as z6 } from "zod";
+
+// src/tools/node-config-schemas.ts
 import { z as z5 } from "zod";
+var longText = z5.string().max(2e5, "Text must be 200000 characters or less");
+var taskStatus = z5.enum(["todo", "in_progress", "in_review", "done", "cancelled"]);
+var workflowInputDefSchema = z5.object({
+  key: z5.string().regex(
+    /^[A-Za-z_][A-Za-z0-9_]*$/,
+    "key must be a valid identifier \u2014 it becomes {{inputs.<key>}}"
+  ).max(100).describe("Identifier the value is read by, as {{inputs.<key>}}"),
+  label: V.shortText.describe("What the run dialog calls this field"),
+  type: z5.enum(["text", "textarea", "number", "select", "boolean", "project", "branch"]).describe("Which control the run dialog shows, and how a supplied value is checked"),
+  required: z5.boolean().optional().describe("A run cannot start without a value"),
+  defaultValue: V.shortText.optional().describe(
+    'Used when the run supplies nothing. A number must be finite, a boolean "true" or "false", a select one of its options'
+  ),
+  options: z5.array(
+    z5.object({
+      value: V.shortText.describe("What {{inputs.<key>}} expands to"),
+      label: V.shortText.describe("What the dialog shows")
+    }).loose()
+  ).optional().describe("Choices for a select; a select without any is refused"),
+  placeholder: V.shortText.optional().describe("Hint shown in an empty field"),
+  description: V.shortText.optional().describe("Help text shown under the field")
+}).loose().superRefine((def, ctx) => {
+  const options = def.options ?? [];
+  if (def.type === "select" && options.length === 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["options"],
+      message: `select input "${def.key}" declares no options, so the run dialog could offer nothing`
+    });
+  }
+  if (def.defaultValue === void 0) return;
+  if (def.type === "number" && !Number.isFinite(Number(def.defaultValue))) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["defaultValue"],
+      message: `default "${def.defaultValue}" for number input "${def.key}" is not a finite number`
+    });
+  }
+  if (def.type === "boolean" && !["true", "false"].includes(def.defaultValue)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["defaultValue"],
+      message: `default "${def.defaultValue}" for boolean input "${def.key}" must be "true" or "false"`
+    });
+  }
+  if (def.type === "select" && options.length > 0 && !options.some((o) => o.value === def.defaultValue)) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["defaultValue"],
+      message: `default "${def.defaultValue}" for select input "${def.key}" is not one of its options`
+    });
+  }
+});
+var workflowInputsSchema = z5.array(workflowInputDefSchema).superRefine((inputs, ctx) => {
+  const seen = /* @__PURE__ */ new Set();
+  inputs.forEach((def, index) => {
+    if (seen.has(def.key)) {
+      ctx.addIssue({
+        code: "custom",
+        path: [index, "key"],
+        message: `duplicate input key "${def.key}" \u2014 only one value can survive under {{inputs.${def.key}}}`
+      });
+    }
+    seen.add(def.key);
+  });
+});
+var projectFilter = V.name.optional().describe("Only fire for this project, by name. Omit to fire for every project");
+var triggerConfigSchema = z5.discriminatedUnion("triggerType", [
+  z5.object({
+    triggerType: z5.literal("manual").describe("Runs when someone starts it, or execute_workflow"),
+    contextual: z5.boolean().optional().describe(
+      "Offered from a task card or terminal right-click, inheriting its folder, branch and worktree as {{context.*}}"
+    ),
+    inputs: workflowInputsSchema.optional().describe("Parameters asked for before each run, read as {{inputs.<key>}}")
+  }).loose(),
+  z5.object({
+    triggerType: z5.literal("once").describe("Runs once at a set time"),
+    runAt: V.shortText.describe("When to run, as an ISO 8601 date-time")
+  }).loose(),
+  z5.object({
+    triggerType: z5.literal("recurring").describe("Runs on a cron schedule"),
+    cron: V.shortText.describe('Five-field cron expression, e.g. "0 9 * * 1-5"'),
+    timezone: V.shortText.optional().describe('IANA zone the cron is read in, e.g. "Europe/Madrid". Defaults to the machine')
+  }).loose(),
+  z5.object({
+    triggerType: z5.literal("taskCreated").describe("Runs when a task is created; the task is {{task.*}}"),
+    projectFilter
+  }).loose(),
+  z5.object({
+    triggerType: z5.literal("taskStatusChanged").describe(
+      "Runs when a task moves between statuses; the task is {{task.*}}, the move {{trigger.fromStatus}} and {{trigger.toStatus}}"
+    ),
+    projectFilter,
+    fromStatus: taskStatus.optional().describe("Only when it leaves this status"),
+    toStatus: taskStatus.optional().describe("Only when it enters this status")
+  }).loose(),
+  z5.object({
+    triggerType: z5.literal("sessionRestored").describe(
+      "Runs when a session comes back after a quit, crash or reboot; {{trigger.restore}} says cold or warm"
+    ),
+    projectFilter,
+    restore: z5.enum(["cold", "any"]).optional().describe(
+      "cold (default): only when a process starts again. any: also when a pane reattaches to one still running"
+    ),
+    concurrency: z5.enum(["perProject", "unbounded"]).optional().describe(
+      "perProject (default) runs one at a time per project, so restored sessions do not race for one port"
+    )
+  }).loose(),
+  z5.object({
+    triggerType: z5.literal("connectorPoll").describe(
+      "Polls a connection on a cron and runs once per new item; the item is {{connectorItem.*}}"
+    ),
+    connectionId: V.id.describe("Connection to poll, from list_connections"),
+    event: V.shortText.describe(
+      "Event type from the connector's manifest, e.g. issueCreated (list_connector_actions shows them)"
+    ),
+    cron: V.shortText.describe("How often to poll, as a five-field cron expression"),
+    timezone: V.shortText.optional().describe("IANA zone the cron is read in")
+  }).loose(),
+  z5.object({
+    triggerType: z5.literal("webhook").describe(
+      "Runs when the local webhook route receives a request; its body, headers and query are {{trigger.*}}"
+    ),
+    method: z5.enum(["POST", "GET"]).describe("HTTP method the route answers"),
+    token: V.shortText.describe(
+      "Secret path segment; a request without it is refused. Use a long random string"
+    )
+  }).loose()
+]);
+var launchAgentNodeConfigSchema = z5.object({
+  agentType: z5.enum(["claude", "copilot", "codex", "opencode", "gemini", "fromTask"]).describe(
+    "Which agent CLI runs. fromTask uses the task's assigned agent, so it needs a task in scope (a task trigger, taskId or taskFromQueue)"
+  ),
+  model: V.shortText.optional().describe('Model passed to the CLI as written, e.g. "opus". Needs a concrete agentType'),
+  projectName: z5.string().max(200).describe("Registered project the agent works in, by name (list_projects)"),
+  projectPath: z5.string().max(1e3).describe("That project's absolute path; templates such as {{context.projectPath}} work"),
+  prompt: V.prompt.optional().describe("What the agent is asked to do. Templates expand before it is sent"),
+  headless: z5.boolean().optional().describe(
+    "Run in the background and wait for it to finish, so later steps can read its output. Without it the agent opens in a terminal tab and the run does not wait on its answer"
+  ),
+  outputSchema: z5.record(z5.string(), z5.unknown()).optional().describe(
+    "JSON Schema its final answer must match (headless only). Each top-level property becomes {{steps.<slug>.<field>}}; an answer that does not match fails the step"
+  ),
+  timeoutMs: z5.number().int().positive().optional().describe(
+    "How long a headless run may take before it is killed and the step fails, in milliseconds. Defaults to the app setting"
+  ),
+  worktreeMode: z5.enum(["none", "new", "fromStep", "existing"]).optional().describe(
+    "Where it works: none (the project folder), new (a fresh git worktree), fromStep (the worktree an earlier step made), existing (existingWorktreePath)"
+  ),
+  worktreeFromStepSlug: V.shortText.optional().describe(
+    "For worktreeMode fromStep: slug of the earlier agent step whose worktree to reuse"
+  ),
+  existingWorktreePath: z5.string().max(1e3).optional().describe("For worktreeMode existing: absolute path of the worktree to work in"),
+  useWorktree: z5.union([z5.boolean(), z5.literal("fromContext")]).optional().describe(
+    "Older switch for a new worktree; prefer worktreeMode. fromContext inherits it from a contextual manual trigger"
+  ),
+  branch: V.shortText.optional().describe("Branch to check out or create for the worktree"),
+  args: z5.array(V.shortText).optional().describe("Extra command-line arguments for the agent CLI"),
+  displayName: V.shortText.optional().describe("Name shown on the session tab"),
+  remoteHostId: V.id.optional().describe("Run on this remote host instead of this machine"),
+  promptDelayMs: z5.number().nonnegative().optional().describe("Wait this long after the agent starts before sending the prompt, in milliseconds"),
+  taskId: V.id.optional().describe("Task the session is attached to"),
+  taskFromQueue: z5.boolean().optional().describe("Take the project's next todo task and attach the session to it")
+}).loose().refine((c) => !c.outputSchema || c.headless === true, {
+  // The engine only parses typed output for headless runs; reject a config that
+  // declares a schema it would silently ignore instead of accepting a lie.
+  message: "outputSchema requires headless: true",
+  path: ["outputSchema"]
+});
+var scriptConfigSchema = z5.object({
+  scriptType: z5.enum(["bash", "powershell", "python", "node"]).describe("Interpreter the script runs under"),
+  scriptContent: longText.describe(
+    "The script. Templates expand before it runs, so quote them as data. Its stdout is {{steps.<slug>.output}}; a non-zero exit fails the step"
+  ),
+  cwd: z5.string().max(1e3).optional().describe("Directory it runs in. Defaults to projectPath"),
+  projectName: z5.string().max(200).optional().describe("Project the script belongs to, by name"),
+  projectPath: z5.string().max(1e3).optional().describe("That project's absolute path, used as the working directory when cwd is unset"),
+  args: z5.array(V.shortText).optional().describe("Arguments passed to the script"),
+  secretsFrom: V.id.optional().describe(
+    "Connection whose stored secrets become this script's environment variables at run time, so no secret is written into the workflow"
+  ),
+  runId: V.id.optional().describe("Set by the engine; leave it out")
+}).loose();
+var conditionConfigSchema = z5.object({
+  variable: longText.describe(
+    "The value to test, usually a template such as {{steps.review.approved}}"
+  ),
+  operator: z5.enum(["equals", "notEquals", "contains", "notContains", "isEmpty", "isNotEmpty"]).describe("How variable is compared with value. Comparisons are on text"),
+  value: longText.optional().describe("What variable is compared with; ignored by isEmpty and isNotEmpty")
+}).loose();
+var approvalConfigSchema = z5.object({
+  message: longText.optional().describe("The question the reviewer is asked. Templates expand when the gate opens"),
+  timeoutMs: z5.number().int().positive().optional().describe("Reject automatically after this long, in milliseconds. Omit to wait for ever"),
+  view: longText.optional().describe(
+    "A review page shown beside the question: HTML, or the path of a .html file, with templates filled in when the gate opens"
+  ),
+  edit: longText.optional().describe(
+    "Text the reviewer may rewrite, as a template. Later steps read the result as {{steps.<gate>.text}}. When it expands to a JSON list of records the reviewer sees a table, and the rows they keep are {{steps.<gate>.items}}"
+  ),
+  feedback: z5.object({
+    from: V.id.describe(
+      "Id of an earlier step, outside any loop body, that leads to this gate. Send back re-runs everything from it to the gate"
+    ),
+    maxRounds: z5.number().int().min(2).max(MAX_GATE_ROUNDS).describe(`How many times the gate may ask, the first included (2 to ${MAX_GATE_ROUNDS})`)
+  }).loose().optional().describe(
+    "Lets the reviewer send the work back with a comment instead of only approving or rejecting; the comment is {{steps.<gate>.feedback}} to the steps that redo it"
+  )
+}).loose();
+var createTaskFromItemConfigSchema = z5.object({
+  nodeType: z5.literal("createTaskFromItem").optional().describe("Always createTaskFromItem"),
+  project: z5.string().max(200).describe(
+    "Project the task lands in, by name, or fromConnection to use the connection's execution project"
+  ),
+  initialStatus: taskStatus.describe(
+    "Status of a newly created task. Re-syncing an existing one never changes its status"
+  )
+}).loose();
+var callConnectorActionConfigSchema = z5.object({
+  nodeType: z5.literal("callConnectorAction").optional().describe("Always callConnectorAction"),
+  connectionId: z5.string().max(100).describe("Connection the action runs against, from list_connections"),
+  action: V.shortText.describe(
+    "Action type from the connector, e.g. commentOnPullRequest; list_connector_actions lists them with their args"
+  ),
+  actionLabel: V.shortText.optional().describe("The action's display name, for the canvas"),
+  connectorId: V.shortText.optional().describe("Connector the action belongs to, for a step placed before a connection exists"),
+  args: z5.record(z5.string(), longText).optional().describe(
+    "The action's arguments by name, every value a string template; a list or object a template names arrives as JSON text. list_connector_actions gives each action's args"
+  )
+}).loose();
+var httpRequestConfigSchema = z5.object({
+  nodeType: z5.literal("httpRequest").optional().describe("Always httpRequest"),
+  method: z5.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).describe("HTTP method"),
+  url: z5.string().max(2048).describe(
+    "Absolute URL, or a path resolved against the profile's base URL. Templates expand"
+  ),
+  headers: z5.record(z5.string(), longText).optional().describe("Request headers. Names are literal; values are templates"),
+  body: longText.optional().describe("Request body as a template; empty sends none"),
+  profileConnectionId: V.id.optional().describe(
+    "An http connection whose base URL and auth are applied server-side, so no credential sits in the workflow"
+  )
+}).loose();
+var loopConfigSchema = z5.object({
+  nodeType: z5.literal("loop").optional().describe("Always loop"),
+  mode: z5.enum(["repeat", "forEach"]).optional().describe(
+    `repeat (default) runs the body up to maxIterations times; forEach runs it once for each item of items, with no cap on how many`
+  ),
+  items: longText.optional().describe(
+    "For forEach: the list to walk, as a template naming it, e.g. {{steps.gate.items}}. JSON text of a list works too, and so does an object holding exactly one list. Each pass reads its item as {{loop.item}} or {{loop.item.<field>}}"
+  ),
+  bodyNodeIds: z5.array(V.id).min(1).describe(
+    "Ids of the steps the loop runs each pass. Wire them with edges: loop -> the entry steps, then between body steps, and from the last body steps to the step after the loop"
+  ),
+  maxIterations: z5.number().optional().describe(
+    `For repeat: how many passes at most, a whole number from 1 to ${MAX_LOOP_ITERATIONS}. Required for repeat, ignored for forEach`
+  ),
+  until: conditionConfigSchema.optional().describe(
+    "Checked after each pass; the loop stops early once it holds, e.g. {{steps.review.approved}} equals true"
+  )
+}).loose().superRefine((config, ctx) => {
+  if (config.mode === "forEach") {
+    if (!config.items?.trim()) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["items"],
+        message: "a forEach loop needs items: a template naming the list to walk"
+      });
+    }
+    return;
+  }
+  const max = config.maxIterations;
+  if (typeof max !== "number" || !Number.isInteger(max) || max < 1 || max > MAX_LOOP_ITERATIONS) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["maxIterations"],
+      message: `a repeat loop needs maxIterations as a whole number from 1 to ${MAX_LOOP_ITERATIONS}`
+    });
+  }
+});
+var edgeSchema = z5.object({
+  id: V.id.describe("Unique within the workflow"),
+  source: V.id.describe("Id of the node that runs first"),
+  target: V.id.describe("Id of the node that runs after it"),
+  // Which branch of a `condition` node this edge represents. Omit for normal
+  // edges; required to wire both outcomes of a condition.
+  conditionBranch: z5.enum(["true", "false"]).optional().describe(
+    "On an edge leaving a condition: which outcome takes it. Wire both. Omit on every other edge"
+  )
+});
+var NODE_TYPES = [
+  "trigger",
+  "launchAgent",
+  "script",
+  "condition",
+  "approval",
+  "createTaskFromItem",
+  "callConnectorAction",
+  "httpRequest",
+  "loop"
+];
+var configSchemaByType = {
+  trigger: triggerConfigSchema,
+  launchAgent: launchAgentNodeConfigSchema,
+  script: scriptConfigSchema,
+  condition: conditionConfigSchema,
+  approval: approvalConfigSchema,
+  createTaskFromItem: createTaskFromItemConfigSchema,
+  callConnectorAction: callConnectorActionConfigSchema,
+  httpRequest: httpRequestConfigSchema,
+  loop: loopConfigSchema
+};
+function nodeConfigIssues(type, config) {
+  const result = configSchemaByType[type].safeParse(config);
+  return result.success ? [] : result.error.issues;
+}
 
 // ../shared/src/workflow-portability.ts
 var PROJECT_PATH_TOKEN = "{{project.path}}";
@@ -3270,168 +3658,73 @@ function residualAbsolutePaths(portable) {
 }
 
 // src/tools/workflows.ts
-var launchAgentConfigSchema = z5.object({
-  agentType: z5.enum(["claude", "copilot", "codex", "opencode", "gemini"]),
+var launchAgentConfigSchema = z6.object({
+  agentType: z6.enum(["claude", "copilot", "codex", "opencode", "gemini"]),
   projectName: V.name,
   projectPath: V.absolutePath,
-  args: z5.array(V.shortText).optional(),
+  args: z6.array(V.shortText).optional(),
   displayName: V.shortText.optional(),
   branch: V.shortText.optional(),
   // boolean | 'fromContext' — `'fromContext'` only valid when the workflow's
   // manual trigger is contextual (validated at runtime, not here).
-  useWorktree: z5.union([z5.boolean(), z5.literal("fromContext")]).optional(),
+  useWorktree: z6.union([z6.boolean(), z6.literal("fromContext")]).optional(),
   remoteHostId: V.id.optional(),
   prompt: V.prompt.optional(),
-  promptDelayMs: z5.number().optional(),
+  promptDelayMs: z6.number().optional(),
   taskId: V.id.optional(),
-  taskFromQueue: z5.boolean().optional(),
+  taskFromQueue: z6.boolean().optional(),
   // Runs the agent in the background and waits for it to finish (required for
   // typed output). Opens a terminal tab when false/omitted.
-  headless: z5.boolean().optional(),
+  headless: z6.boolean().optional(),
   // JSON Schema the agent's final answer must satisfy (headless only). When set,
   // the engine parses a matching object from the run and exposes its fields as
   // `{{steps.<slug>.<field>}}` for downstream condition nodes.
-  outputSchema: z5.record(z5.string(), z5.unknown()).optional()
+  outputSchema: z6.record(z6.string(), z6.unknown()).optional()
 }).refine((c) => !c.outputSchema || c.headless === true, {
   // The engine only parses typed output for headless runs; reject a config that
   // declares a schema it would silently ignore instead of accepting a lie.
   message: "outputSchema requires headless: true",
   path: ["outputSchema"]
 });
-var workflowInputDefSchema = z5.object({
-  key: z5.string().regex(
-    /^[A-Za-z_][A-Za-z0-9_]*$/,
-    "key must be a valid identifier \u2014 it becomes {{inputs.<key>}}"
-  ).max(100),
-  label: V.shortText,
-  type: z5.enum(["text", "textarea", "number", "select", "boolean", "project", "branch"]),
-  required: z5.boolean().optional(),
-  defaultValue: V.shortText.optional(),
-  options: z5.array(z5.object({ value: V.shortText, label: V.shortText })).optional(),
-  placeholder: V.shortText.optional(),
-  description: V.shortText.optional()
-}).superRefine((def, ctx) => {
-  const options = def.options ?? [];
-  if (def.type === "select" && options.length === 0) {
-    ctx.addIssue({
-      code: "custom",
-      path: ["options"],
-      message: `select input "${def.key}" declares no options, so the run dialog could offer nothing`
-    });
-  }
-  if (def.defaultValue === void 0) return;
-  if (def.type === "number" && !Number.isFinite(Number(def.defaultValue))) {
-    ctx.addIssue({
-      code: "custom",
-      path: ["defaultValue"],
-      message: `default "${def.defaultValue}" for number input "${def.key}" is not a finite number`
-    });
-  }
-  if (def.type === "boolean" && !["true", "false"].includes(def.defaultValue)) {
-    ctx.addIssue({
-      code: "custom",
-      path: ["defaultValue"],
-      message: `default "${def.defaultValue}" for boolean input "${def.key}" must be "true" or "false"`
-    });
-  }
-  if (def.type === "select" && options.length > 0 && !options.some((o) => o.value === def.defaultValue)) {
-    ctx.addIssue({
-      code: "custom",
-      path: ["defaultValue"],
-      message: `default "${def.defaultValue}" for select input "${def.key}" is not one of its options`
-    });
-  }
-});
-var workflowInputsSchema = z5.array(workflowInputDefSchema).superRefine((inputs, ctx) => {
-  const seen = /* @__PURE__ */ new Set();
-  inputs.forEach((def, index) => {
-    if (seen.has(def.key)) {
-      ctx.addIssue({
-        code: "custom",
-        path: [index, "key"],
-        message: `duplicate input key "${def.key}" \u2014 only one value can survive under {{inputs.${def.key}}}`
-      });
-    }
-    seen.add(def.key);
-  });
-});
-var triggerConfigSchema = z5.union([
-  z5.object({
-    triggerType: z5.literal("manual"),
-    contextual: z5.boolean().optional(),
-    inputs: workflowInputsSchema.optional()
-  }),
-  z5.object({ triggerType: z5.literal("once"), runAt: V.shortText }),
-  z5.object({
-    triggerType: z5.literal("recurring"),
-    cron: V.shortText,
-    timezone: V.shortText.optional()
-  }),
-  z5.object({ triggerType: z5.literal("taskCreated"), projectFilter: V.name.optional() }),
-  z5.object({
-    triggerType: z5.literal("taskStatusChanged"),
-    projectFilter: V.name.optional(),
-    fromStatus: z5.enum(["todo", "in_progress", "in_review", "done", "cancelled"]).optional(),
-    toStatus: z5.enum(["todo", "in_progress", "in_review", "done", "cancelled"]).optional()
-  }),
-  z5.object({
-    triggerType: z5.literal("connectorPoll"),
-    connectionId: V.id,
-    event: V.shortText,
-    cron: V.shortText,
-    timezone: V.shortText.optional()
-  }),
-  z5.object({
-    triggerType: z5.literal("webhook"),
-    method: z5.enum(["POST", "GET"]),
-    token: V.shortText
-  })
-]);
-var nodeSchema = z5.object({
-  id: V.id,
-  // Full node palette — parity with the editor. `config` is a passthrough so
-  // each type carries its own shape (ConditionConfig, ApprovalConfig, etc.).
-  type: z5.enum([
-    "trigger",
-    "launchAgent",
-    "script",
-    "condition",
-    "approval",
-    "createTaskFromItem",
-    "callConnectorAction",
-    "httpRequest",
-    "loop"
-  ]),
-  label: V.shortText,
+var nodeShapeSchema = z6.object({
+  id: V.id.describe("Unique within the workflow; edges and bodyNodeIds refer to it"),
+  // Full node palette — parity with the editor.
+  type: z6.enum(NODE_TYPES).describe("Node type; describe_workflow_nodes gives the config each one takes"),
+  label: V.shortText.describe("Name shown on the canvas and in run history"),
   // Referenced by typed step vars as `{{steps.<slug>.<field>}}`. Set one on any
   // node whose output a later node consumes.
-  slug: V.shortText.optional(),
-  config: z5.record(z5.string(), z5.unknown()),
-  position: z5.object({ x: z5.number(), y: z5.number() }),
+  slug: V.shortText.optional().describe("Name later steps read this one by, as {{steps.<slug>.<field>}}"),
+  config: z6.record(z6.string(), z6.unknown()).describe("The type's own settings; describe_workflow_nodes has the schema for each type"),
+  position: z6.object({ x: z6.number(), y: z6.number() }).describe("Where the node sits on the canvas"),
   // Omitted means stop. Declared here because the object strips what it does
   // not name: without it a workflow authored over MCP could never say a step
   // is survivable, and the field would be dropped without complaint.
-  onError: z5.enum(["stop", "continue"]).optional()
-}).superRefine((node, ctx) => {
-  if (node.type !== "loop") return;
-  const config = node.config;
-  if (!Array.isArray(config.bodyNodeIds) || config.bodyNodeIds.length === 0) {
-    ctx.addIssue({
-      code: "custom",
-      path: ["config", "bodyNodeIds"],
-      message: `loop "${node.id}" must list at least one body step in bodyNodeIds`
-    });
+  onError: z6.enum(["stop", "continue"]).optional().describe("stop (default) ends the run when this step fails; continue carries on past it")
+});
+function describeConfigIssues(node) {
+  return nodeConfigIssues(node.type, node.config).map(
+    (issue) => `${["config", ...issue.path.map(String)].join(".")}: ${issue.message}`
+  );
+}
+function checkNodeConfigs(nodes, stored) {
+  const errors = [];
+  const warnings = [];
+  for (const node of nodes) {
+    const issues = describeConfigIssues(node);
+    if (issues.length === 0) continue;
+    const before = stored.find((n) => n.id === node.id && n.type === node.type);
+    const untouched = before !== void 0 && isDeepStrictEqual(before.config, node.config);
+    const line = `node "${node.label || node.id}" ${issues.join(", ")}`;
+    if (untouched) warnings.push(line);
+    else errors.push(line);
   }
-  const max = config.maxIterations;
-  if (typeof max !== "number" || !Number.isInteger(max) || max < 1 || max > MAX_LOOP_ITERATIONS) {
-    ctx.addIssue({
-      code: "custom",
-      path: ["config", "maxIterations"],
-      message: `loop "${node.id}" needs maxIterations as a whole number from 1 to ${MAX_LOOP_ITERATIONS}`
-    });
+  return { errors, warnings };
+}
+var nodeSchema = nodeShapeSchema.superRefine((node, ctx) => {
+  for (const issue of nodeConfigIssues(node.type, node.config)) {
+    ctx.addIssue({ code: "custom", path: ["config", ...issue.path], message: issue.message });
   }
 });
-var MAX_LOOP_ITERATIONS = 10;
 function validateLoopBodies(nodes) {
   const ids = new Set(nodes.map((n) => n.id));
   const errors = [];
@@ -3449,14 +3742,21 @@ function validateLoopBodies(nodes) {
   }
   return errors;
 }
-var edgeSchema = z5.object({
-  id: V.id,
-  source: V.id,
-  target: V.id,
-  // Which branch of a `condition` node this edge represents. Omit for normal
-  // edges; required to wire both outcomes of a condition.
-  conditionBranch: z5.enum(["true", "false"]).optional()
-});
+function validateLoopStructures(nodes, edges) {
+  const graph = nodes;
+  const wires = edges;
+  return graph.filter((node) => node.type === "loop").flatMap((loop) => {
+    const error = loopStructureError(graph, wires, loop);
+    return error ? [`loop "${loop.label || loop.id}": ${error}`] : [];
+  });
+}
+function validateGraph(nodes, edges) {
+  return [
+    ...validateLoopBodies(nodes),
+    ...validateLoopStructures(nodes, edges),
+    ...validateGateFeedback(nodes, edges)
+  ];
+}
 function buildGraphFromFlat(trigger, actions) {
   const nodes = [];
   const edges = [];
@@ -3594,6 +3894,7 @@ var ANSWERED = {
 };
 function validateGateFeedback(nodes, edges) {
   const errors = [];
+  const owners = loopBodyOwners(nodes);
   for (const node of nodes) {
     if (node.type !== "approval" || node.config?.feedback === void 0) continue;
     const feedback = node.config.feedback;
@@ -3602,7 +3903,12 @@ function validateGateFeedback(nodes, edges) {
     const source2 = nodes.find((n) => n.id === from);
     if (!source2) errors.push(`gate "${name}" redoes from unknown step "${from}"`);
     else if (source2.type === "trigger") errors.push(`gate "${name}" cannot redo from its trigger`);
-    else if (nodesBetween(from, node.id, edges).size === 0) {
+    else if (owners.has(from)) {
+      const loop = nodes.find((n) => n.id === owners.get(from));
+      errors.push(
+        `gate "${name}" redoes from "${source2.label || from}", which is inside loop "${loop?.label || owners.get(from)}"; redo from the loop, or a step before it`
+      );
+    } else if (nodesBetween(from, node.id, edges).size === 0) {
       errors.push(`gate "${name}" redoes from "${source2.label || from}", which does not lead to it`);
     }
     const rounds = Number(feedback?.maxRounds);
@@ -3665,17 +3971,19 @@ function registerWorkflowTools(server) {
   );
   server.tool(
     "create_workflow",
-    'Create a new workflow. Accepts either full nodes/edges (advanced mode \u2014 every node type is supported: trigger, launchAgent, script, condition, approval, createTaskFromItem, callConnectorAction; wire condition outcomes with edge conditionBranch "true"/"false") or a convenience flat format (trigger + actions array). Give a node a slug to reference its output downstream as {{steps.<slug>.<field>}}. A headless launchAgent with an outputSchema returns typed fields for condition nodes.',
+    'Create a workflow: a graph of steps started by one trigger. Call describe_workflow_nodes first \u2014 it gives the config schema, outputs and rules of every node type, the template namespaces, and a complete example to copy. Pass nodes and edges (every node type is supported), or the convenience format (trigger + actions, a straight line of agents).\n\nNode types: trigger (exactly one, what starts the run), launchAgent (an AI agent; headless with an outputSchema gives typed fields), script (bash/python/node/powershell), condition (branches: wire both outcomes with edge conditionBranch "true" and "false"), approval (a human gate; can show a table to edit and send work back), createTaskFromItem, callConnectorAction (an action of a connected service; list_connector_actions gives its args), httpRequest, and loop.\n\nGive a node a slug and later steps read its output as {{steps.<slug>.<field>}}.\n\nLoops: config.bodyNodeIds lists the steps the loop runs each pass. Wire an edge from the loop to each body entry step, edges between body steps, and from the last body steps to the step after the loop; nothing outside the loop may point into its body, and a condition inside it keeps both branches inside. mode "repeat" runs up to maxIterations (1-10) passes, stopping early when until holds; mode "forEach" runs once per item of items (e.g. {{steps.gate.items}}), and body steps read {{loop.item.<field>}}. A loop body cannot hold an approval, a trigger or another loop.\n\nEach node config is checked against its type, and the graph for loop and gate wiring; a refusal names the node and field.',
     {
       name: V.title.describe("Workflow name"),
       trigger: triggerConfigSchema.optional().describe("Trigger config (convenience mode). Defaults to manual."),
-      actions: z5.array(launchAgentConfigSchema).optional().describe("Actions to execute (convenience mode). Auto-generates graph."),
-      nodes: z5.array(nodeSchema).optional().describe("Full graph nodes (advanced mode)"),
-      edges: z5.array(edgeSchema).optional().describe("Full graph edges (advanced mode)"),
+      actions: z6.array(launchAgentConfigSchema).optional().describe("Agents to run one after another (convenience mode). Auto-generates the graph."),
+      nodes: z6.array(nodeSchema).optional().describe("Graph nodes; pass with edges. describe_workflow_nodes has each config schema"),
+      edges: z6.array(edgeSchema).optional().describe("Graph edges; pass with nodes. A step runs once every edge into it has run"),
       icon: V.shortText.optional().describe("Lucide icon name (default: zap)"),
       icon_color: V.hexColor.optional().describe("Hex color (default: #6366f1)"),
-      enabled: z5.boolean().optional().describe("Whether workflow is enabled (default: true)"),
-      stagger_delay_ms: z5.number().optional().describe("Delay in ms between actions")
+      enabled: z6.boolean().optional().describe(
+        "Whether its trigger fires on its own (default: true). Manual runs work either way"
+      ),
+      stagger_delay_ms: z6.number().optional().describe("Delay in ms between actions")
     },
     async (args) => {
       let nodes;
@@ -3683,11 +3991,10 @@ function registerWorkflowTools(server) {
       if (args.nodes && args.edges) {
         nodes = args.nodes;
         edges = args.edges;
-        const loose = nodes;
-        const loopErrors = [...validateLoopBodies(loose), ...validateGateFeedback(loose, edges)];
-        if (loopErrors.length > 0) {
+        const graphErrors = validateGraph(nodes, edges);
+        if (graphErrors.length > 0) {
           return {
-            content: [{ type: "text", text: `Error: ${loopErrors.join("; ")}` }],
+            content: [{ type: "text", text: `Error: ${graphErrors.join("; ")}` }],
             isError: true
           };
         }
@@ -3715,17 +4022,19 @@ function registerWorkflowTools(server) {
   );
   server.tool(
     "update_workflow",
-    "Update a workflow's properties",
+    "Change a workflow. Only the fields you pass change; nodes and edges each replace the whole list, so read the workflow first (list_workflows), edit it, and send the full list back. Checked like create_workflow: each node config against its type (describe_workflow_nodes), and the graph for loop and gate wiring. A node whose config you left exactly as stored is let through with a warning even if it breaks a newer rule, so an older workflow stays editable; fix what the warning names when you can.",
     {
       workflow_id: V.id.optional().describe("Workflow ID (from list_workflows)"),
       id: V.id.optional().describe("Deprecated alias for workflow_id"),
-      name: V.title.optional(),
-      nodes: z5.array(nodeSchema).optional(),
-      edges: z5.array(edgeSchema).optional(),
-      icon: V.shortText.optional(),
-      icon_color: V.hexColor.optional(),
-      enabled: z5.boolean().optional(),
-      stagger_delay_ms: z5.number().optional()
+      name: V.title.optional().describe("New name"),
+      // The shape only: configs are checked in the handler, where an untouched
+      // stored config can be told apart from a new mistake.
+      nodes: z6.array(nodeShapeSchema).optional().describe("Every node of the workflow, replacing the stored list"),
+      edges: z6.array(edgeSchema).optional().describe("Every edge of the workflow, replacing the stored list"),
+      icon: V.shortText.optional().describe("Lucide icon name"),
+      icon_color: V.hexColor.optional().describe("Hex color"),
+      enabled: z6.boolean().optional().describe("Whether its trigger fires on its own. Manual runs work either way"),
+      stagger_delay_ms: z6.number().optional().describe("Delay in ms between actions")
     },
     async (args) => {
       const resolved = resolveWorkflowId(args);
@@ -3740,20 +4049,31 @@ function registerWorkflowTools(server) {
           isError: true
         };
       }
-      const updates = {};
-      if (args.name !== void 0) updates.name = args.name;
+      const warnings = [];
       if (args.nodes !== void 0) {
-        const loose = args.nodes;
+        const { errors, warnings: legacy } = checkNodeConfigs(args.nodes, workflow.nodes);
+        if (errors.length > 0) {
+          return {
+            content: [{ type: "text", text: `Error: ${errors.join("; ")}` }],
+            isError: true
+          };
+        }
+        warnings.push(...legacy);
+      }
+      if (args.nodes !== void 0 || args.edges !== void 0) {
+        const nodes = args.nodes ?? workflow.nodes;
         const edges = args.edges ?? workflow.edges;
-        const loopErrors = [...validateLoopBodies(loose), ...validateGateFeedback(loose, edges)];
-        if (loopErrors.length > 0) {
+        const graphErrors = validateGraph(nodes, edges);
+        if (graphErrors.length > 0) {
           return {
-            content: [{ type: "text", text: `Error: ${loopErrors.join("; ")}` }],
+            content: [{ type: "text", text: `Error: ${graphErrors.join("; ")}` }],
             isError: true
           };
         }
-        updates.nodes = args.nodes;
       }
+      const updates = {};
+      if (args.name !== void 0) updates.name = args.name;
+      if (args.nodes !== void 0) updates.nodes = args.nodes;
       if (args.edges !== void 0) updates.edges = args.edges;
       if (args.icon !== void 0) updates.icon = args.icon;
       if (args.icon_color !== void 0) updates.iconColor = args.icon_color;
@@ -3761,8 +4081,17 @@ function registerWorkflowTools(server) {
       if (args.stagger_delay_ms !== void 0) updates.staggerDelayMs = args.stagger_delay_ms;
       await dbUpdateWorkflow(resolved.id, updates);
       dbSignalChange();
+      const saved = JSON.stringify({ ...workflow, ...updates }, null, 2);
       return {
-        content: [{ type: "text", text: JSON.stringify({ ...workflow, ...updates }, null, 2) }]
+        content: [
+          {
+            type: "text",
+            text: warnings.length > 0 ? `Warning: saved, but these configs were stored before and break a current rule, so they were kept as they are:
+  - ${warnings.join("\n  - ")}
+
+${saved}` : saved
+          }
+        ]
       };
     }
   );
@@ -3797,7 +4126,7 @@ function registerWorkflowTools(server) {
     {
       workflow_id: V.id.optional().describe("Filter by workflow ID"),
       task_id: V.id.optional().describe("Filter by task ID (runs triggered by this task)"),
-      limit: z5.number().int().min(1).max(100).optional().describe("Max results (default: 20)")
+      limit: z6.number().int().min(1).max(100).optional().describe("Max results (default: 20)")
     },
     async (args) => {
       if (args.workflow_id && args.task_id) {
@@ -3877,13 +4206,13 @@ The run is stopped by the instance holding it, so confirm with list_workflow_run
     "Approve, reject, or send back the approval gate a workflow run is parked on, the way the Vorn app does. Requires the Vorn app to be running: the decision is broadcast, and the instance holding the run is what resumes it. Read what is being approved first \u2014 list_workflow_runs names the waiting node and what it asks.",
     {
       run_id: V.id.describe("Run ID (from list_workflow_runs)"),
-      decision: z5.enum(["approve", "reject", "changes"]).describe(
+      decision: z6.enum(["approve", "reject", "changes"]).describe(
         "approve lets the run go on; reject ends it; changes sends the work back to the step the gate redoes from, with your comment, and the gate asks again"
       ),
-      comment: z5.string().max(2e4).optional().describe(
+      comment: z6.string().max(2e4).optional().describe(
         "Required for changes: what to change. Optional on approve and reject; kept with the run."
       ),
-      edited: z5.string().max(2e5).optional().describe(
+      edited: z6.string().max(2e5).optional().describe(
         "Your rewrite of the gate's editable text, when it has one. Kept beside the original, and read by later steps as {{steps.<gate>.text}}. Ignored on reject."
       ),
       node_id: V.id.optional().describe("The waiting node, when a run has more than one gate open")
@@ -3930,19 +4259,22 @@ The run is stopped by the instance holding it, so confirm with list_workflow_run
       const gateNode = approvalNode(workflow, target.nodeId);
       const asked = run.nodeStates.find((n) => n.nodeId === target.nodeId)?.message ?? askedBy(gateNode);
       try {
-        const answer = await rpcCall("workflow:resolveGate", {
-          runId: args.run_id,
-          nodeId: target.nodeId,
-          decision: args.decision,
-          ...args.comment?.trim() && { comment: args.comment.trim() },
-          ...args.edited?.trim() && { edited: args.edited.trim() }
-        });
+        const answer = await rpcCall(
+          "workflow:resolveGate",
+          {
+            runId: args.run_id,
+            nodeId: target.nodeId,
+            decision: args.decision,
+            ...args.comment?.trim() && { comment: args.comment.trim() },
+            ...args.edited?.trim() && { edited: args.edited.trim() }
+          }
+        );
         if (answer?.accepted === false) {
           return {
             content: [
               {
                 type: "text",
-                text: args.decision === "changes" ? "Error: this gate takes no changes now: it has no step to redo from, or its rounds are used up. Approve or reject it instead." : "Error: the gate did not take that answer. Check list_workflow_runs."
+                text: answer.reason ? `Error: ${answer.reason}` : args.decision === "changes" ? "Error: this gate takes no changes now: it has no step to redo from, or its rounds are used up. Approve or reject it instead." : "Error: the gate did not take that answer. Check list_workflow_runs."
               }
             ],
             isError: true
@@ -3974,7 +4306,7 @@ The decision went out; the instance holding the run acts on it, so a desktop has
     "Get scheduler info for a workflow: execution log or next scheduled run. Requires the Vorn app to be running.",
     {
       workflow_id: V.id.optional().describe("Workflow ID (required for next_run, optional for log)"),
-      info: z5.enum(["log", "next_run"]).optional().describe("What to retrieve (default: log)")
+      info: z6.enum(["log", "next_run"]).optional().describe("What to retrieve (default: log)")
     },
     async (args) => {
       const info = args.info ?? "log";
@@ -4012,7 +4344,7 @@ The decision went out; the instance holding the run acts on it, so a desktop has
     "Run a workflow now, as if triggered manually. Supply values for any parameters the workflow declares (see the trigger node's inputs); declared defaults fill in anything omitted. Requires the Vorn app to be running. Returns as soon as the run is queued \u2014 poll list_workflow_runs for the outcome. Runs of one workflow go side by side; only a run repeating one started in the last ten seconds with the same inputs is refused as a duplicate.",
     {
       workflow_id: V.id.describe("Workflow ID (from list_workflows)"),
-      inputs: z5.record(z5.string(), z5.union([z5.string(), z5.number(), z5.boolean()])).optional().describe("Values for the declared parameters, keyed by input key ({{inputs.<key>}})")
+      inputs: z6.record(z6.string(), z6.union([z6.string(), z6.number(), z6.boolean()])).optional().describe("Values for the declared parameters, keyed by input key ({{inputs.<key>}})")
     },
     async (args) => {
       const workflow = (await dbListWorkflows()).find((w) => w.id === args.workflow_id);
@@ -4120,7 +4452,7 @@ Warning: ${unnamed.length} step(s) point at a connection this install could not
     "import_workflow",
     "Import a workflow exported by export_workflow, resolving {{project.path}} and {{project.name}} against a registered project. Recorded connection requirements are rebound when this machine has one unambiguous match, and reported as still to connect otherwise. The id is derived from the bundle and the workflow's slug, so importing the same file again updates it in place instead of creating a duplicate.",
     {
-      workflow: z5.string().max(5e5).describe("The exported workflow JSON"),
+      workflow: z6.string().max(5e5).describe("The exported workflow JSON"),
       project_name: V.name.describe("Registered project to resolve paths against"),
       bundle: V.name.optional().describe("Namespace for the derived id (default: the project name)")
     },
@@ -4168,11 +4500,7 @@ Warning: ${unnamed.length} step(s) point at a connection this install could not
           isError: true
         };
       }
-      const loose = parsed.nodes;
-      const loopErrors = [
-        ...validateLoopBodies(loose),
-        ...validateGateFeedback(loose, parsed.edges)
-      ];
+      const loopErrors = validateGraph(parsed.nodes, parsed.edges);
       if (loopErrors.length > 0) {
         return {
           content: [{ type: "text", text: `Error: ${loopErrors.join("; ")}` }],
@@ -4219,6 +4547,330 @@ Still to connect: ${pending}` : "")
   );
 }
 
+// src/tools/describe-nodes.ts
+import { z as z7 } from "zod";
+var COMMON_OUTPUTS = [
+  { field: "status", description: "success or error" },
+  { field: "error", description: "Why it failed, or empty" }
+];
+var DOCS = {
+  trigger: {
+    summary: "What starts a run: by hand, on a schedule, on a task event, when a session is restored, by polling a connection, or on a webhook. config.triggerType picks which.",
+    outputs: [],
+    rules: [
+      "A workflow has exactly one trigger, and no edge points into it.",
+      "A manual trigger may declare inputs; each is read anywhere as {{inputs.<key>}}, and execute_workflow takes their values.",
+      "What the trigger carries is read as {{task.*}}, {{trigger.*}} or {{connectorItem.*}}, depending on its type."
+    ]
+  },
+  launchAgent: {
+    summary: "Starts an AI coding agent in a project with a prompt. Headless, it runs in the background and the run waits for its answer; otherwise it opens a terminal tab.",
+    outputs: [
+      { field: "output", description: "The agent's final answer (headless)" },
+      {
+        field: "<outputSchema property>",
+        description: "Each top-level property of config.outputSchema, parsed from the answer (headless only)"
+      },
+      { field: "worktreePath", description: "The directory the agent worked in" },
+      ...COMMON_OUTPUTS
+    ],
+    rules: [
+      "outputSchema requires headless: true, and an answer that does not match it fails the step.",
+      "Read typed fields in a condition, e.g. variable {{steps.review.approved}} equals true, rather than matching words in output.",
+      "agentType fromTask needs a task in scope: a task trigger, taskId or taskFromQueue. model needs a concrete agentType.",
+      "worktreeMode fromStep reuses the worktree of the earlier agent step named by worktreeFromStepSlug."
+    ]
+  },
+  script: {
+    summary: "Runs a bash, python, node or powershell script.",
+    outputs: [
+      { field: "output", description: "What the script printed to stdout" },
+      ...COMMON_OUTPUTS
+    ],
+    rules: [
+      "Templates expand into the script text before it runs. Keep a value as data rather than code, e.g. inside a quoted heredoc: cat <<'EOF' ... EOF.",
+      "A non-zero exit fails the step.",
+      "secretsFrom names a connection whose secrets become environment variables, so no secret is written into the workflow."
+    ]
+  },
+  condition: {
+    summary: "Compares a value, usually a step output, and sends the run down its true or its false branch.",
+    outputs: [{ field: "output", description: '"true" or "false"' }, ...COMMON_OUTPUTS],
+    rules: [
+      'Give it two outgoing edges, one with conditionBranch "true" and one with "false". Steps on the branch not taken are skipped.',
+      'Comparisons are on text: equals true matches the text "true".',
+      "Inside a loop body, both branches must stay inside the body."
+    ]
+  },
+  approval: {
+    summary: "Pauses the run until a person approves or rejects, in the app or with resolve_gate. It can show a review page, let the reviewer rewrite some text, and send the work back with a comment.",
+    outputs: [
+      { field: "text", description: "The editable text as the reviewer left it" },
+      {
+        field: "items",
+        description: "When the editable text is a JSON list of records: the rows the reviewer kept, as a list, ready for a forEach loop"
+      },
+      { field: "feedback", description: "The reviewer's latest comment" },
+      { field: "feedbackAll", description: "Every comment, one line per round" },
+      { field: "round", description: "Which time the gate asked, from 1" },
+      ...COMMON_OUTPUTS
+    ],
+    rules: [
+      "A gate cannot sit inside a loop body.",
+      "When edit expands to a JSON list of records the reviewer sees a table; a rewrite that is no longer valid JSON is refused.",
+      `feedback.from is the id of an earlier step that leads to this gate, not the trigger and not a step inside a loop. Sending back re-runs every step from it to the gate. maxRounds is 2 to ${MAX_GATE_ROUNDS}.`,
+      "A reject ends the run."
+    ]
+  },
+  createTaskFromItem: {
+    summary: "Creates a task from the connector item that started the run, or updates the one it created before.",
+    outputs: [
+      { field: "output", description: "Imported or Updated, with the item id and title" },
+      ...COMMON_OUTPUTS
+    ],
+    rules: [
+      "Needs {{connectorItem.*}}: put it after a connectorPoll trigger.",
+      "Re-syncing an item updates its title and description but never its status."
+    ]
+  },
+  callConnectorAction: {
+    summary: "Runs one action of a connected service (a comment, an issue, a merge...) with arguments built from templates.",
+    outputs: [
+      { field: "output", description: "The action result as text" },
+      {
+        field: "<the action's output fields>",
+        description: "Each field the action declares in its outputSchema; list_connector_actions gives them"
+      },
+      ...COMMON_OUTPUTS
+    ],
+    rules: [
+      "connectionId comes from list_connections; action and its args from list_connector_actions.",
+      "A step waits, rather than fails, when its connection needs signing in again."
+    ]
+  },
+  httpRequest: {
+    summary: "Sends one HTTP request, optionally through an http connection that adds auth.",
+    outputs: [
+      { field: "body", description: "Response body, JSON-parsed when possible" },
+      { field: "headers", description: "Response headers, by lower-case name" },
+      {
+        field: "output",
+        description: 'HTTP <code>, e.g. "HTTP 404": the way to read the response status'
+      },
+      {
+        field: "status",
+        description: "success or error: the step's own status, which replaces the response code under this name"
+      },
+      { field: "error", description: "Why it failed, or empty" }
+    ],
+    rules: [
+      "Put credentials in an http connection (profileConnectionId), not in headers.",
+      'Any answer succeeds, a 4xx or 5xx included: to act on the code, test {{steps.<slug>.output}} (e.g. contains "HTTP 2"). Only a network error or the 30 second timeout fails the step. Redirects are not followed.'
+    ]
+  },
+  loop: {
+    summary: `Runs a group of steps (its body) several times: repeat up to ${MAX_LOOP_ITERATIONS} passes, stopping early when until holds, or forEach once per item of a list.`,
+    outputs: [
+      { field: "output", description: "How many passes ran" },
+      { field: "passes", description: "How many passes ran, as a number" },
+      {
+        field: "count",
+        description: "How many passes were planned: maxIterations, or the number of items"
+      },
+      {
+        field: "results",
+        description: "Per pass: {index, item?, status, steps: {<slug>: {output, status, error, ...}}}; each output cut to loopResultOutputChars"
+      },
+      {
+        field: "outputs",
+        description: "Per pass, the output of the last body step that ran (on the branch taken), cut to loopResultOutputChars"
+      },
+      ...COMMON_OUTPUTS
+    ],
+    rules: [
+      "bodyNodeIds lists every step in the body. Wire the loop to each body entry step, body steps to each other, and the last body steps to the step after the loop.",
+      "Nothing outside the loop may point into its body; only the loop starts its steps.",
+      "A body cannot hold an approval gate, a trigger or another loop, and cannot contain a cycle.",
+      `repeat needs maxIterations, 1 to ${MAX_LOOP_ITERATIONS}. forEach needs items and has no cap.`,
+      "Body steps read {{loop.item}} / {{loop.item.<field>}} (forEach), {{loop.index}} from 0, {{loop.number}} from 1 and {{loop.count}}.",
+      "A body step that fails ends the loop there, unless that step has onError: continue.",
+      "Inside the body, {{steps.<slug>.*}} of a body step is this pass. After the loop, read the passes through {{steps.<loop>.results}} or .outputs."
+    ]
+  }
+};
+var EXAMPLE = {
+  nodes: [
+    {
+      id: "start",
+      type: "trigger",
+      label: "Start",
+      config: {
+        triggerType: "manual",
+        inputs: [{ key: "pullRequest", label: "Pull request", type: "text", required: true }]
+      },
+      position: { x: 0, y: 0 }
+    },
+    {
+      id: "review",
+      type: "callConnectorAction",
+      label: "Read review findings",
+      slug: "review",
+      config: {
+        nodeType: "callConnectorAction",
+        connectionId: "<connection id from list_connections>",
+        action: "listReviewFindings",
+        args: { pullRequest: "{{inputs.pullRequest}}" }
+      },
+      position: { x: 0, y: 140 }
+    },
+    {
+      id: "gate",
+      type: "approval",
+      label: "Pick findings to post",
+      slug: "gate",
+      config: {
+        message: "Keep the findings worth a comment, and delete the rest.",
+        edit: "{{steps.review.findings}}"
+      },
+      position: { x: 0, y: 280 }
+    },
+    {
+      id: "loop",
+      type: "loop",
+      label: "For each finding",
+      slug: "loop",
+      config: {
+        nodeType: "loop",
+        mode: "forEach",
+        items: "{{steps.gate.items}}",
+        bodyNodeIds: ["severe", "comment", "skip"]
+      },
+      position: { x: 0, y: 420 }
+    },
+    {
+      id: "severe",
+      type: "condition",
+      label: "High severity?",
+      slug: "severe",
+      config: { variable: "{{loop.item.severity}}", operator: "equals", value: "high" },
+      position: { x: 0, y: 560 }
+    },
+    {
+      id: "comment",
+      type: "callConnectorAction",
+      label: "Comment on the line",
+      slug: "comment",
+      config: {
+        nodeType: "callConnectorAction",
+        connectionId: "<connection id from list_connections>",
+        action: "commentOnPullRequest",
+        args: {
+          pullRequest: "{{inputs.pullRequest}}",
+          path: "{{loop.item.path}}",
+          line: "{{loop.item.line}}",
+          body: "{{loop.item.body}}"
+        }
+      },
+      position: { x: -160, y: 700 }
+    },
+    {
+      id: "skip",
+      type: "script",
+      label: "Note the skip",
+      slug: "skip",
+      config: {
+        scriptType: "bash",
+        scriptContent: "cat <<'EOF'\nNot posted: {{loop.item.path}}\nEOF\n"
+      },
+      position: { x: 160, y: 700 }
+    },
+    {
+      id: "summary",
+      type: "script",
+      label: "Summarise",
+      slug: "summary",
+      config: {
+        scriptType: "bash",
+        scriptContent: "cat <<'EOF'\nWhat each finding came to:\n{{steps.loop.outputs}}\nEOF\n"
+      },
+      position: { x: 0, y: 840 }
+    }
+  ],
+  edges: [
+    { id: "e-start-review", source: "start", target: "review" },
+    { id: "e-review-gate", source: "review", target: "gate" },
+    { id: "e-gate-loop", source: "gate", target: "loop" },
+    { id: "e-loop-severe", source: "loop", target: "severe" },
+    { id: "e-severe-comment", source: "severe", target: "comment", conditionBranch: "true" },
+    { id: "e-severe-skip", source: "severe", target: "skip", conditionBranch: "false" },
+    { id: "e-comment-summary", source: "comment", target: "summary" },
+    { id: "e-skip-summary", source: "skip", target: "summary" }
+  ]
+};
+function jsonSchema(schema) {
+  return z7.toJSONSchema(schema, { io: "input", unrepresentable: "any" });
+}
+var WORKFLOW_NODES_REFERENCE = {
+  nodeTypes: Object.fromEntries(
+    NODE_TYPES.map((type) => [
+      type,
+      {
+        summary: DOCS[type].summary,
+        configSchema: jsonSchema(configSchemaByType[type]),
+        outputs: DOCS[type].outputs,
+        rules: DOCS[type].rules
+      }
+    ])
+  ),
+  edgeSchema: jsonSchema(edgeSchema),
+  limits: {
+    repeatMaxIterations: MAX_LOOP_ITERATIONS,
+    forEachMaxItems: "uncapped",
+    maxGateRounds: MAX_GATE_ROUNDS,
+    templateTextChars: MAX_OUTPUT_LENGTH,
+    loopResultOutputChars: LOOP_RESULT_OUTPUT_CHARS
+  },
+  templates: {
+    syntax: "{{namespace.path.to.field}} anywhere a config takes text. An unknown namespace is left as written; a known one with nothing there becomes empty. Text longer than templateTextChars keeps its end.",
+    namespaces: {
+      steps: "{{steps.<slug>.<field>}}: the output of an earlier step, by its slug; the fields are listed under each node type",
+      task: "{{task.title}}, .description, .id, .status, .branch, .projectName: the task a task trigger fired for",
+      trigger: "{{trigger.*}}: what the trigger carried: fromStatus/toStatus, restore, or a webhook body, headers and query",
+      connectorItem: "{{connectorItem.title}}, .body, .externalId, .externalUrl: the item a connectorPoll trigger fired for",
+      inputs: "{{inputs.<key>}}: the values a manual run was started with",
+      context: "{{context.cwd}}, .projectPath, .projectName, .branch, .worktreePath: where a contextual manual run was started from",
+      loop: "{{loop.item}}, {{loop.item.<field>}}, {{loop.index}} (from 0), {{loop.number}} (from 1), {{loop.count}}: only inside a loop body"
+    },
+    examples: [
+      "{{steps.review.approved}}",
+      "{{steps.gate.items}}",
+      "{{loop.item.path}}",
+      "{{steps.loop.outputs}}",
+      "{{inputs.pullRequest}}",
+      "{{task.title}}"
+    ]
+  },
+  example: EXAMPLE
+};
+function registerDescribeNodesTool(server) {
+  server.tool(
+    "describe_workflow_nodes",
+    "The reference for writing a workflow: for each node type its config schema, the outputs later steps read, and the rules create_workflow checks; the edge schema; limits; the template namespaces; and a complete example workflow to adapt. Call it before create_workflow or update_workflow.",
+    {
+      types: z7.array(z7.enum(NODE_TYPES)).optional().describe("Only these node types. Omit for all nine")
+    },
+    async (args) => {
+      const reference = args.types?.length ? {
+        ...WORKFLOW_NODES_REFERENCE,
+        nodeTypes: Object.fromEntries(
+          args.types.map((type) => [type, WORKFLOW_NODES_REFERENCE.nodeTypes[type]])
+        )
+      } : WORKFLOW_NODES_REFERENCE;
+      return { content: [{ type: "text", text: JSON.stringify(reference, null, 2) }] };
+    }
+  );
+}
+
 // src/tools/config.ts
 function registerConfigTools(server) {
   server.tool(
@@ -4233,7 +4885,7 @@ function registerConfigTools(server) {
 
 // src/tools/workspaces.ts
 import crypto5 from "crypto";
-import { z as z6 } from "zod";
+import { z as z8 } from "zod";
 function registerWorkspaceTools(server) {
   server.tool("list_workspaces", "List all workspaces", async () => {
     const workspaces = await dbListWorkspaces();
@@ -4270,7 +4922,7 @@ function registerWorkspaceTools(server) {
       name: V.name.optional().describe("New name"),
       icon: V.shortText.optional().describe("Lucide icon name"),
       icon_color: V.hexColor.optional().describe("Hex color for icon"),
-      order: z6.number().int().min(0).optional().describe("Sort order")
+      order: z8.number().int().min(0).optional().describe("Sort order")
     },
     async (args) => {
       const existing = await dbListWorkspaces();
@@ -4318,7 +4970,7 @@ function registerWorkspaceTools(server) {
 }
 
 // src/tools/connectors.ts
-import { z as z7 } from "zod";
+import { z as z9 } from "zod";
 var PROBE_TIMEOUT_MS = 12e4;
 var json = (value) => ({
   content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
@@ -4347,8 +4999,8 @@ function registerConnectorTools(server) {
     "list_connectors",
     "List every connector and extension: the ones built into Vorn, the ones installable from a package, and how many connections each already has. A connector polls a service; an extension adds footers and panes to a session card and says what it may touch. Use this before creating a workflow that calls a connector action, or to find an id to install.",
     {
-      installable_only: z7.boolean().optional().describe("Only connectors that are not set up yet"),
-      kind: z7.enum(["connector", "extension"]).optional().describe("Only one kind: what polls a service, or what shows on a card")
+      installable_only: z9.boolean().optional().describe("Only connectors that are not set up yet"),
+      kind: z9.enum(["connector", "extension"]).optional().describe("Only one kind: what polls a service, or what shows on a card")
     },
     async (args) => {
       const [builtIns, snapshot, connections, statuses, packs] = await Promise.all([
@@ -4426,7 +5078,7 @@ function registerConnectorTools(server) {
     "List configured connector connections, including when each last synced and the error from its last failure. Use this to diagnose a connector that is not producing tasks.",
     {
       connector_id: V.id.optional().describe("Only connections for this connector"),
-      failing_only: z7.boolean().optional().describe("Only connections whose last sync failed")
+      failing_only: z9.boolean().optional().describe("Only connections whose last sync failed")
     },
     async (args) => {
       const connections = await rpcCall("connection:list", {
@@ -4495,8 +5147,8 @@ function registerConnectorTools(server) {
       name: V.title.optional().describe("Connection name (defaults to the connector name)"),
       project: V.name.optional().describe("Vorn project tasks should be created in"),
       trigger: V.shortText.optional().describe("Trigger type to configure (defaults to the first the connector offers)"),
-      env: z7.record(z7.string(), z7.string()).optional().describe("Non-secret environment variables the connector needs"),
-      sync_interval_minutes: z7.number().int().min(1).max(1440).optional()
+      env: z9.record(z9.string(), z9.string()).optional().describe("Non-secret environment variables the connector needs"),
+      sync_interval_minutes: z9.number().int().min(1).max(1440).optional()
     },
     async (args) => {
       const { items: catalog } = await rpcCall("connector:catalog");
@@ -4608,7 +5260,7 @@ function registerConnectorTools(server) {
     {
       connection_id: V.id.describe("Connection ID"),
       action: V.shortText.describe("Action name from list_connector_actions"),
-      args: z7.record(z7.string(), z7.unknown()).optional().describe("Action arguments")
+      args: z9.record(z9.string(), z9.unknown()).optional().describe("Action arguments")
     },
     async (args) => {
       const result = await rpcCall("connection:executeAction", {
@@ -4660,7 +5312,7 @@ function plural(count, word) {
 
 // src/tools/browser.ts
 import crypto6 from "crypto";
-import { z as z8 } from "zod";
+import { z as z10 } from "zod";
 function sessionId(env = process.env) {
   const id = env.VORN_SESSION_ID;
   return id && id.length > 0 ? id : null;
@@ -4718,9 +5370,9 @@ function registerBrowserTools(server) {
     "read_page",
     'Read your session browser pane as an accessibility tree. Interactive elements carry a "ref" you can pass to browser_interact. Prefer this over screenshot: it is far cheaper and gives you actionable handles. Long pages paginate \u2014 pass the returned nextCursor back as `cursor`. When the page is a design artifact it also returns "artifact" (what the file declares) and "artifactValues" (what it is currently showing). Work from artifactValues: a person can turn a control without spending a turn, so the value on screen is routinely not the default in the file.',
     {
-      filter: z8.enum(["interactive", "all"]).optional().describe('"interactive" (default) returns only actionable elements; "all" adds text'),
+      filter: z10.enum(["interactive", "all"]).optional().describe('"interactive" (default) returns only actionable elements; "all" adds text'),
       cursor: V.shortText.optional().describe("nextCursor from a previous read_page result"),
-      limit: z8.number().int().min(1).max(200).optional().describe("Max nodes (default 200)")
+      limit: z10.number().int().min(1).max(200).optional().describe("Max nodes (default 200)")
     },
     async (args) => withSession(
       async (id) => pageResult(
@@ -4751,7 +5403,7 @@ function registerBrowserTools(server) {
   server.tool(
     "read_console_messages",
     "Read console output captured from your session browser pane since it opened.",
-    { limit: z8.number().int().min(1).max(200).optional().describe("Max messages (default 50)") },
+    { limit: z10.number().int().min(1).max(200).optional().describe("Max messages (default 50)") },
     async (args) => withSession(
       async (id) => pageResult(
         await rpcCall("browser:consoleMessages", {
@@ -4764,7 +5416,7 @@ function registerBrowserTools(server) {
   server.tool(
     "read_network_requests",
     "Read network requests captured from your session browser pane since it opened.",
-    { limit: z8.number().int().min(1).max(200).optional().describe("Max requests (default 50)") },
+    { limit: z10.number().int().min(1).max(200).optional().describe("Max requests (default 50)") },
     async (args) => withSession(
       async (id) => pageResult(
         await rpcCall("browser:networkRequests", {
@@ -4777,7 +5429,7 @@ function registerBrowserTools(server) {
   server.tool(
     "browser_screenshot",
     "Capture your session browser pane as a PNG. This is the expensive last resort \u2014 reach for read_page first, and use this only when layout or rendering is the actual question.",
-    { full_page: z8.boolean().optional().describe("Capture beyond the viewport") },
+    { full_page: z10.boolean().optional().describe("Capture beyond the viewport") },
     async (args) => withSession(async (id) => {
       const { data } = await rpcCall("browser:screenshot", {
         sessionId: id,
@@ -4799,7 +5451,7 @@ function registerBrowserTools(server) {
     "Find elements in your session browser pane whose accessible name contains some text. Cheaper than reading the whole page when you already know what you are looking for.",
     {
       text: V.shortText.describe("Text to match against element names (case-insensitive)"),
-      limit: z8.number().int().min(1).max(50).optional().describe("Max matches (default 20)")
+      limit: z10.number().int().min(1).max(50).optional().describe("Max matches (default 20)")
     },
     async (args) => withSession(
       async (id) => pageResult(
@@ -4815,12 +5467,12 @@ function registerBrowserTools(server) {
     "browser_interact",
     'Act on your session browser pane: click, hover, type, press a key, or scroll. Address the target by "ref" from read_page where possible \u2014 refs survive reflow, coordinates do not. A ref from before a navigation is refused rather than guessed at; re-read the page. A ref target is scrolled into view first, so it does not need to be on screen already. "ok" means the input was dispatched, not that the page did what you expected \u2014 read the state back after anything that matters.',
     {
-      action: z8.enum(["click", "hover", "type", "key", "scroll"]).describe('What to do. "type" clicks the target first when one is given.'),
+      action: z10.enum(["click", "hover", "type", "key", "scroll"]).describe('What to do. "type" clicks the target first when one is given.'),
       ref: V.shortText.optional().describe("Element ref from read_page"),
-      x: z8.number().optional().describe("Viewport x, when no ref is available"),
-      y: z8.number().optional().describe("Viewport y, when no ref is available"),
+      x: z10.number().optional().describe("Viewport x, when no ref is available"),
+      y: z10.number().optional().describe("Viewport y, when no ref is available"),
       text: V.description.optional().describe('Text for "type", or the key name for "key" (e.g. "Enter")'),
-      delta_y: z8.number().optional().describe("Scroll amount in pixels (default 400)")
+      delta_y: z10.number().optional().describe("Scroll amount in pixels (default 400)")
     },
     async (args) => withSession(async (id) => {
       await rpcCall("browser:interact", {
@@ -4846,9 +5498,9 @@ function registerBrowserTools(server) {
     "browser_tabs",
     'List, add, close, or switch tabs in your session browser pane. "close" and "select" take a zero-based index \u2014 call "list" first to see what those indices name, since a tab that redirected or followed a link is no longer on the page it was opened with. Closing the last remaining tab closes the pane.',
     {
-      action: z8.enum(["list", "add", "close", "select"]).describe("What to do with tabs"),
+      action: z10.enum(["list", "add", "close", "select"]).describe("What to do with tabs"),
       url: V.url.optional().describe('URL for "add"'),
-      index: z8.number().int().min(0).optional().describe("Zero-based tab index for close/select")
+      index: z10.number().int().min(0).optional().describe("Zero-based tab index for close/select")
     },
     async (args) => withSession(async (id) => {
       if (args.action === "list") {
@@ -4881,7 +5533,7 @@ function registerBrowserTools(server) {
   server.tool(
     "browser_history",
     "Step back or forward through your session browser pane's own history \u2014 the same thing the pane's back and forward buttons do. Fails when there is no page to move to, rather than quietly staying put.",
-    { direction: z8.enum(["back", "forward"]).describe("Which way to step") },
+    { direction: z10.enum(["back", "forward"]).describe("Which way to step") },
     async (args) => withSession(async (id) => {
       const result = await rpcCall("browser:history", {
         sessionId: id,
@@ -4895,7 +5547,7 @@ function registerBrowserTools(server) {
 }
 
 // src/tools/device.ts
-import { z as z9 } from "zod";
+import { z as z11 } from "zod";
 var DEVICE_FENCE = "DEVICE CONTENT";
 var required = (description) => V.shortText.min(1, "Value must not be empty").describe(description);
 async function withSession2(run) {
@@ -4960,9 +5612,9 @@ function registerDeviceTools(server) {
     "read_screen",
     'Read your claimed simulator as an accessibility tree. Elements carry a "ref" you can pass to device_interact. Prefer this over device_screenshot: it is far cheaper and gives you handles rather than pixels. Coordinates are in POINTS, which is what taps take \u2014 a screenshot is typically 3x larger in pixels. Long screens paginate via nextCursor.',
     {
-      filter: z9.enum(["interactive", "all"]).optional().describe('"interactive" (default) returns only actionable elements; "all" adds text'),
+      filter: z11.enum(["interactive", "all"]).optional().describe('"interactive" (default) returns only actionable elements; "all" adds text'),
       cursor: V.shortText.optional().describe("nextCursor from a previous read_screen result"),
-      limit: z9.number().int().min(1).max(200).optional().describe("Max elements (default 200)")
+      limit: z11.number().int().min(1).max(200).optional().describe("Max elements (default 200)")
     },
     async (args) => withSession2(
       async (id) => pageResult(
@@ -4981,7 +5633,7 @@ function registerDeviceTools(server) {
     "Find elements on your claimed simulator whose label or accessibility identifier contains some text. Searches the whole screen, not just the first page read_screen would return.",
     {
       text: required("Text to match against labels and identifiers (case-insensitive)"),
-      limit: z9.number().int().min(1).max(50).optional().describe("Max matches (default 20)")
+      limit: z11.number().int().min(1).max(50).optional().describe("Max matches (default 20)")
     },
     async (args) => withSession2(
       async (id) => pageResult(
@@ -4998,17 +5650,17 @@ function registerDeviceTools(server) {
     "device_interact",
     'Act on your claimed simulator: tap, swipe, type, press a hardware button, or long-press. Address the target by "ref" from read_screen where possible. Coordinates are in POINTS. A ref from before an earlier interaction is refused rather than guessed at \u2014 read the screen again. A swipe starting at the very edge of the screen is refused too: iOS claims those as system gestures and swallows them, which looks to you like nothing happened.',
     {
-      action: z9.enum(["tap", "swipe", "type", "button", "press"]).describe('"press" is a long press; "button" takes a name in `text`'),
+      action: z11.enum(["tap", "swipe", "type", "button", "press"]).describe('"press" is a long press; "button" takes a name in `text`'),
       ref: required("Element ref from read_screen or device_find").optional(),
-      x: z9.number().optional().describe("Screen x in points, when no ref is available"),
-      y: z9.number().optional().describe("Screen y in points, when no ref is available"),
-      to_x: z9.number().optional().describe("Swipe destination x, in points"),
-      to_y: z9.number().optional().describe("Swipe destination y, in points"),
+      x: z11.number().optional().describe("Screen x in points, when no ref is available"),
+      y: z11.number().optional().describe("Screen y in points, when no ref is available"),
+      to_x: z11.number().optional().describe("Swipe destination x, in points"),
+      to_y: z11.number().optional().describe("Swipe destination y, in points"),
       text: V.description.optional().describe(
         'Text for "type", or the button name for "button" (HOME, LOCK, SIRI, SIDE_BUTTON)'
       ),
-      duration: z9.number().min(0).max(30).optional().describe('Seconds to hold, for "press"'),
-      system_gesture: z9.boolean().optional().describe("Allow a stroke starting in the bezel band, when a system gesture is the intent")
+      duration: z11.number().min(0).max(30).optional().describe('Seconds to hold, for "press"'),
+      system_gesture: z11.boolean().optional().describe("Allow a stroke starting in the bezel band, when a system gesture is the intent")
     },
     async (args) => withSession2(async (id) => {
       const r = await rpcCall("device:interact", {
@@ -5034,7 +5686,7 @@ function registerDeviceTools(server) {
     "device_screenshot",
     "Capture your claimed simulator as a downscaled PNG. The expensive last resort \u2014 reach for read_screen first, and use this only when layout or rendering is the actual question. The result reports the scale factor: divide an image coordinate by it to get the point coordinate device_interact takes.",
     {
-      max_edge: z9.number().int().min(200).max(2e3).optional().describe("Longest edge of the returned image in pixels (default 1000)")
+      max_edge: z11.number().int().min(200).max(2e3).optional().describe("Longest edge of the returned image in pixels (default 1000)")
     },
     async (args) => withSession2(async (id) => {
       const r = await rpcCall("device:screenshot", { sessionId: id, maxEdge: args.max_edge });
@@ -5089,7 +5741,7 @@ Screen is ${r.screen.width}x${r.screen.height} points. Image pixels are ${r.scal
   server.tool(
     "device_logs",
     "Read log output captured from your claimed simulator since it was claimed.",
-    { limit: z9.number().int().min(1).max(500).optional().describe("Max lines (default 100)") },
+    { limit: z11.number().int().min(1).max(500).optional().describe("Max lines (default 100)") },
     async (args) => withSession2(
       async (id) => pageResult(
         await rpcCall("device:logs", { sessionId: id, limit: args.limit }),
@@ -5122,6 +5774,7 @@ function createMcpServer(version) {
   registerProjectTools(server);
   registerTaskTools(server);
   registerWorkflowTools(server);
+  registerDescribeNodesTool(server);
   registerWorkspaceTools(server);
   return server;
 }
@@ -5135,7 +5788,7 @@ console.warn = (...args) => _origError("[mcp:warn]", ...args);
 console.error = (...args) => _origError("[mcp:error]", ...args);
 async function main() {
   configManager.init();
-  const version = true ? "0.7.2" : createRequire(import.meta.url)("../package.json").version;
+  const version = true ? "0.7.3" : createRequire(import.meta.url)("../package.json").version;
   const server = createMcpServer(version);
   const transport = new StdioServerTransport();
   await server.connect(transport);