Repository: mastra-ai/mastra
Pull request #4291: Add vNext Workflow API reference
Author: login: manthanguptaa
Created: 2025-05-16T10:32:16Z | Merged: 2025-05-16T13:29:39Z

## Description

This PR adds
- API reference for vnext workflows
- Smaller additions to vnext workflow docs
- Adds comments to code snippets in vnext workflow docs 

## Related Issue(s)

<!-- Link to the issue(s) this PR addresses, using hashtag notation: #123 -->

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
- [x] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update

## Checklist

- [ ] I have made corresponding changes to the documentation (if applicable)
- [ ] I have added tests that prove my fix is effective or that my feature works



Diff:
diff --git a/docs/src/content/en/docs/workflows-vnext/flow-control.mdx b/docs/src/content/en/docs/workflows-vnext/flow-control.mdx
index 72b10ab360f..64d57239d4a 100644
--- a/docs/src/content/en/docs/workflows-vnext/flow-control.mdx
+++ b/docs/src/content/en/docs/workflows-vnext/flow-control.mdx
@@ -8,10 +8,15 @@ description: "Control flow in Mastra (vNext) workflows allows you to manage bran
 Chain steps to execute in sequence using `.then()`:
 
 ```typescript
-myWorkflow.then(step1).then(step2).then(step3).commit();
+// Chain steps to execute in sequence
+myWorkflow
+  .then(step1) // First step
+  .then(step2) // Second step, receives output from step1
+  .then(step3) // Third step, receives output from step2
+  .commit();
 ```
 
-The output from each step is automatically passed to the next step if schemas match. If the schemas don't match, you can use the `map` function to transform the output to the expected schema.
+The output from each step is automatically passed to the next step if schemas match. If the schemas don't match, you can use the [`map` function](/docs/workflows-vnext/input-data-mapping.mdx) to transform the output to the expected schema.
 Step chaining is type-safe and checked at compile time.
 
 ## Parallel Execution
@@ -19,7 +24,12 @@ Step chaining is type-safe and checked at compile time.
 Execute steps in parallel using `.parallel()`:
 
 ```typescript
-myWorkflow.parallel([step1, step2]).then(step3).commit();
+// Execute step1 and step2 in parallel
+myWorkflow
+  .parallel([step1, step2])
+  // Continue with step3 after both parallel steps complete
+  .then(step3)
+  .commit();
 ```
 
 This executes all steps in the array concurrently, then continues to the next step after all parallel steps complete.
@@ -27,6 +37,7 @@ This executes all steps in the array concurrently, then continues to the next st
 You can also execute entire workflows in parallel:
 
 ```typescript
+// Execute nestedWorkflow1 and nestedWorkflow2 in parallel
 myWorkflow
   .parallel([nestedWorkflow1, nestedWorkflow2])
   .then(finalStep)
@@ -43,13 +54,17 @@ Create conditional branches using `.branch()`:
 myWorkflow
   .then(initialStep)
   .branch([
+    // If value > 50, run highValueStep
     [async ({ inputData }) => inputData.value > 50, highValueStep],
+    // If value is between 11 and 50, run lowValueStep
     [
       async ({ inputData }) => inputData.value > 10 && inputData.value <= 50,
       lowValueStep,
     ],
+    // If value <= 10, run extremelyLowValueStep
     [async ({ inputData }) => inputData.value <= 10, extremelyLowValueStep],
   ])
+  // After branching, continue with finalStep
   .then(finalStep)
   .commit();
 ```
@@ -65,6 +80,7 @@ vNext supports two types of loops. When looping a step (or nested workflow or an
 **Do-While Loop**: Executes a step repeatedly while a condition is true.
 
 ```typescript
+// Repeat incrementStep while value is less than 10
 myWorkflow
   .dowhile(incrementStep, async ({ inputData }) => inputData.value < 10)
   .then(finalStep)
@@ -74,31 +90,19 @@ myWorkflow
 **Do-Until Loop**: Executes a step repeatedly until a condition becomes true.
 
 ```typescript
+// Repeat incrementStep while value is more than 10
 myWorkflow
   .dountil(incrementStep, async ({ inputData }) => inputData.value >= 10)
   .then(finalStep)
   .commit();
 ```
 
-```typescript
-const workflow = createWorkflow({
-  id: "increment-workflow",
-  inputSchema: z.object({
-    value: z.number(),
-  }),
-  outputSchema: z.object({
-    value: z.number(),
-  }),
-})
-  .dountil(incrementStep, async ({ inputData }) => inputData.value >= 10)
-  .then(finalStep);
-```
-
 ## Foreach
 
 Foreach is a step that executes a step for each item in an array type input.
 
 ```typescript
+// Step that adds 11 to the current value
 const mapStep = createStep({
   id: "map",
   description: "Maps (+11) on the current value",
@@ -113,6 +117,7 @@ const mapStep = createStep({
   },
 });
 
+// final step that prints the result
 const finalStep = createStep({
   id: "final",
   description: "Final step that prints the result",
@@ -134,6 +139,7 @@ const counterWorkflow = createWorkflow({
   }),
 });
 
+// Apply mapStep to each item in the input array, then run finalStep
 counterWorkflow.foreach(mapStep).then(finalStep).commit();
 
 const run = counterWorkflow.createRun();
@@ -173,9 +179,9 @@ const mainWorkflow = createWorkflow({
   inputSchema: z.object({...}),
   outputSchema: z.object({...}),
 })
-  .then(initialStep)
-  .then(nestedWorkflow)
-  .then(finalStep)
+  .then(initialStep)    // Run initialStep first
+  .then(nestedWorkflow) // Then run the nested workflow as a step
+  .then(finalStep)      // Finally, run finalStep
   .commit();
 ```
 
@@ -184,6 +190,7 @@ In the above example, the `nestedWorkflow` is used as a step in the `mainWorkflo
 Nested workflows are the main (and only) way compose execution flows beyond simple sequential execution. When using `.branch()` or `.parallel()` to compose execution flows, executing more than just one step necessarily requires a nested workflow, and as a byproduct, a description of how these steps are to be executed.
 
 ```typescript
+// Define a workflow that plans both indoor and outdoor activities in parallel, then synthesizes the results
 const planBothWorkflow = createWorkflow({
   id: "plan-both-workflow",
   inputSchema: forecastSchema,
@@ -192,10 +199,12 @@ const planBothWorkflow = createWorkflow({
   }),
   steps: [planActivities, planIndoorActivities, sythesizeStep],
 })
+  // Run planActivities and planIndoorActivities in parallel
   .parallel([planActivities, planIndoorActivities])
   .then(sythesizeStep)
   .commit();
 
+// Define the main weather workflow
 const weatherWorkflow = createWorkflow({
   id: "weather-workflow-step3-concurrency",
   inputSchema: z.object({
@@ -206,14 +215,17 @@ const weatherWorkflow = createWorkflow({
   }),
   steps: [fetchWeather, planBothWorkflow, planActivities],
 })
+  // First, fetch the weather for the given city
   .then(fetchWeather)
   .branch([
+    // If precipitationChance > 20, plan both indoor and outdoor activities (nested workflow)
     [
       async ({ inputData }) => {
         return inputData?.precipitationChance > 20;
       },
       planBothWorkflow,
     ],
+    // If precipitationChance <= 20, only plan outdoor activities
     [
       async ({ inputData }) => {
         return inputData?.precipitationChance <= 20;
diff --git a/docs/src/content/en/docs/workflows-vnext/overview.mdx b/docs/src/content/en/docs/workflows-vnext/overview.mdx
index 52321a27053..685819f8859 100644
--- a/docs/src/content/en/docs/workflows-vnext/overview.mdx
+++ b/docs/src/content/en/docs/workflows-vnext/overview.mdx
@@ -18,8 +18,8 @@ vNext workflows consist of:
 
 - **Schemas**: Type definitions for inputs and outputs using Zod
 - **Steps**: Individual units of work with defined inputs and outputs
-- **Workflows**: Orchestrations of steps with defined execution patterns. A workflow is also a step and can be used as such in other workflows.
-- **Workflow execution flow**: How steps are executed and connected to each other
+- **Workflow**: A structured sequence of steps designed to accomplish a specific task or process. Workflows define the order, dependencies, and logic for executing steps, and can themselves be reused as steps within other workflows.
+- **Workflow execution flow**: The path and logic followed during a workflow run, including how steps are executed, how data moves between them, and how conditions, branches, and errors are handled.
 
 Schemas are defined using Zod both for inputs and outputs of steps and workflows. Schemas can also dictate what data does a step take when resuming from a suspended state, as well as what contextual information should be passed when suspending a step's execution.
 
@@ -36,6 +36,7 @@ Primitives such as `.then()`, `.parallel()` and `.branch()` describe the executi
 Steps are the building blocks of workflows. Create a step using `createStep`:
 
 ```typescript
+// Create a step with defined input/output schemas and execution logic
 const myStep = createStep({
   id: "my-step",
   description: "Does something useful",
@@ -45,9 +46,11 @@ const myStep = createStep({
   outputSchema: z.object({
     outputValue: z.string(),
   }),
+  // Optional: Define the resume schema for step resumption
   resumeSchema: z.object({
     resumeValue: z.string(),
   }),
+  // Optional: Define the suspend schema for step suspension
   suspendSchema: z.object({
     suspendValue: z.string(),
   }),
@@ -90,11 +93,14 @@ The `execute` function receives a context object with:
 Create a workflow using `createWorkflow`:
 
 ```typescript
+// Create a workflow with defined steps and execution flow
 const myWorkflow = createWorkflow({
   id: "my-workflow",
+  // Define the expected input structure (should match the first step's inputSchema)
   inputSchema: z.object({
     startValue: z.string(),
   }),
+  // Define the expected output structure (should match the last step's outputSchema)
   outputSchema: z.object({
     result: z.string(),
   }),
@@ -105,12 +111,14 @@ const myWorkflow = createWorkflow({
   .then(step3)
   .commit();
 
+// Register workflow with Mastra instance
 const mastra = new Mastra({
   vnext_workflows: {
     myWorkflow,
   },
 });
 
+// Create a run instance of the workflow
 const run = mastra.vnext_getWorkflow("myWorkflow").createRun();
 ```
 
@@ -180,10 +188,10 @@ const parentWorkflow = createWorkflow({
   steps: [myWorkflow, step4],
 });
 parentWorkflow
-  .then(myWorkflow)
+  .then(myWorkflow) // nested workflow
   .then(step4)
-  .then(cloneWorkflow(myWorkflow, { id: "cloned-workflow" }))
-  .then(cloneStep(step4, { id: "cloned-step-4" }))
+  .then(cloneWorkflow(myWorkflow, { id: "cloned-workflow" })) // cloned workflow
+  .then(cloneStep(step4, { id: "cloned-step-4" })) // cloned step
   .commit();
 ```
 
diff --git a/docs/src/content/en/docs/workflows-vnext/suspend-and-resume.mdx b/docs/src/content/en/docs/workflows-vnext/suspend-and-resume.mdx
index 9c77d492f75..a768465e15b 100644
--- a/docs/src/content/en/docs/workflows-vnext/suspend-and-resume.mdx
+++ b/docs/src/content/en/docs/workflows-vnext/suspend-and-resume.mdx
@@ -10,7 +10,7 @@ Complex workflows often need to pause execution while waiting for external input
 Mastra's suspend and resume features let you pause workflow execution at any step, persist the workflow snapshot to storage, and resume execution from the saved snapshot when ready.
 This entire process is automatically managed by Mastra. No config needed, or manual step required from the user.
 
-Storing the workflow snapshot to storage (LibSQL by default) means that the workflow state is permanently preserved across sessions, deployments, and server restarts. This persistence is crucial for workflows that might remain suspended for minutes, hours, or even days while waiting for external input or resources.
+Storing the workflow snapshot to storage means that the workflow state is permanently preserved across sessions, deployments, and server restarts. This persistence is crucial for workflows that might remain suspended for minutes, hours, or even days while waiting for external input or resources.
 
 ## When to Use Suspend/Resume
 
@@ -25,21 +25,25 @@ Common scenarios for suspending workflows include:
 ## How to suspend a step
 
 ```typescript
+// Create a step that handles human input with suspend/resume capabilities
 const humanInputStep = createStep({
   id: "human-input",
   inputSchema: z.object({
     suggestions: z.array(z.string()),
     vacationDescription: z.string(),
   }),
+  // Define the structure of data needed to resume the step
   resumeSchema: z.object({
     selection: z.string(),
   }),
+  // Define the structure of data when suspending (empty in this case)
   suspendSchema: z.object({}),
   outputSchema: z.object({
     selection: z.string().describe("The selection of the user"),
     vacationDescription: z.string(),
   }),
   execute: async ({ inputData, resumeData, suspend }) => {
+    // If no resume data is provided, suspend the step and wait for user input
     if (!resumeData?.selection) {
       await suspend({});
       return {
@@ -72,7 +76,9 @@ When the state is `suspended`, you can identify any and all steps that have been
 const run = counterWorkflow.createRun();
 const result = await run.start({ inputData: { startValue: 0 } });
 
+// Check if the workflow is in suspended state
 if (result.status === "suspended") {
+  // Resume the first suspended step with new data
   const resumedResults = await run.resume({
     step: result.suspended[0],
     resumeData: { newValue: 0 },
@@ -87,7 +93,7 @@ The `suspended` property is of type `string[][]`, where every array is a path to
 ### Resume
 
 ```typescript
-// After getting user input
+// Resume a suspended workflow with user input
 const result = await workflowRun.resume({
   step: userInputStep, // or 'myStepId' as a string
   resumeData: {
@@ -99,6 +105,7 @@ const result = await workflowRun.resume({
 To resume a suspended nested workflow:
 
 ```typescript
+// Resume a suspended nested workflow with user input
 const result = await workflowRun.resume({
   step: [nestedWorkflow, userInputStep], // or ['nestedWorkflowId', 'myStepId'] as a string array
   resumeData: {
diff --git a/docs/src/content/en/reference/_meta.ts b/docs/src/content/en/reference/_meta.ts
index 566e2bbcf44..8372e73b1ae 100644
--- a/docs/src/content/en/reference/_meta.ts
+++ b/docs/src/content/en/reference/_meta.ts
@@ -9,6 +9,7 @@ const meta: Meta = {
   agents: "Agents",
   tools: "Tools",
   workflows: "Workflows",
+  vNextWorkflows: "vNext Workflows",
   networks: "Networks",
   memory: "Memory",
   storage: "Storage",
diff --git a/docs/src/content/en/reference/vNextWorkflows/_meta.ts b/docs/src/content/en/reference/vNextWorkflows/_meta.ts
new file mode 100644
index 00000000000..ba18c3799ac
--- /dev/null
+++ b/docs/src/content/en/reference/vNextWorkflows/_meta.ts
@@ -0,0 +1,19 @@
+const meta = {
+  workflow: "Workflow",
+  step: "createStep()",
+  then: "then()",
+  parallel: "parallel()",
+  branch: "branch()",
+  dowhile: "dowhile()",
+  dountil: "dountil()",
+  foreach: "foreach()",
+  map: "map()",
+  commit: "commit()",
+  "create-run": "createRun()",
+  watch: "watch()",
+  execute: "execute()",
+  resume: "resume()",
+  start: "start()",
+};
+
+export default meta;
diff --git a/docs/src/content/en/reference/vNextWorkflows/branch.mdx b/docs/src/content/en/reference/vNextWorkflows/branch.mdx
new file mode 100644
index 00000000000..dfba067a121
--- /dev/null
+++ b/docs/src/content/en/reference/vNextWorkflows/branch.mdx
@@ -0,0 +1,42 @@
+---
+title: "Reference: Workflow.branch() | Building Workflows | Mastra Docs"
+description: Documentation for the `.branch()` method in workflows, which creates conditional branches between steps.
+---
+
+# Workflow.branch()
+
+The `.branch()` method creates conditional branches between workflow steps, allowing for different paths to be taken based on the result of a previous step.
+
+## Usage
+
+```typescript
+workflow.branch([
+  [async ({ context }) => true, stepOne],
+  [async ({ context }) => false, stepTwo],
+]);
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "steps",
+      type: "[() => boolean, Step]",
+      description: "An array of tuples, each containing a condition function and a step to execute if the condition is true",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "workflow",
+      type: "NewWorkflow",
+      description: "The workflow instance for method chaining",
+    },
+  ]}
+/>
diff --git a/docs/src/content/en/reference/vNextWorkflows/commit.mdx b/docs/src/content/en/reference/vNextWorkflows/commit.mdx
new file mode 100644
index 00000000000..fd4042717f2
--- /dev/null
+++ b/docs/src/content/en/reference/vNextWorkflows/commit.mdx
@@ -0,0 +1,26 @@
+---
+title: "Reference: Workflow.commit() | Building Workflows | Mastra Docs"
+description: Documentation for the `.commit()` method in workflows, which finalizes the workflow and returns the final result.
+---
+
+# Workflow.commit()
+
+The `.commit()` method finalizes the workflow and returns the final result.
+
+## Usage
+
+```typescript
+workflow.then(stepOne).commit();
+```
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "workflow",
+      type: "NewWorkflow",
+      description: "The workflow instance for method chaining",
+    },
+  ]}
+/>
diff --git a/docs/src/content/en/reference/vNextWorkflows/create-run.mdx b/docs/src/content/en/reference/vNextWorkflows/create-run.mdx
new file mode 100644
index 00000000000..414b60d3df5
--- /dev/null
+++ b/docs/src/content/en/reference/vNextWorkflows/create-run.mdx
@@ -0,0 +1,60 @@
+---
+title: "Reference: Workflow.createRun() | Building Workflows | Mastra Docs"
+description: Documentation for the `.createRun()` method in workflows, which creates a new workflow run instance.
+---
+
+# Workflow.createRun()
+
+The `.createRun()` method creates a new workflow run instance, allowing you to execute the workflow with specific input data.
+
+## Usage
+
+```typescript
+const myWorkflow = createWorkflow({
+  id: "my-workflow",
+  inputSchema: z.object({
+    startValue: z.string(),
+  }),
+  outputSchema: z.object({
+    result: z.string(),
+  }),
+  steps: [step1, step2, step3], // Declare steps used in this workflow
+})
+  .then(step1)
+  .then(step2)
+  .then(step3)
+  .commit();
+
+const mastra = new Mastra({
+  vnext_workflows: {
+    myWorkflow,
+  },
+});
+
+const run = mastra.vnext_getWorkflow("myWorkflow").createRun();
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "options",
+      type: "{ runId?: string }",
+      description: "Optional configuration for the run, including a custom run ID",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "run",
+      type: "Run",
+      description: "A new workflow run instance that can be used to execute the workflow",
+    },
+  ]}
+/>
diff --git a/docs/src/content/en/reference/vNextWorkflows/dountil.mdx b/docs/src/content/en/reference/vNextWorkflows/dountil.mdx
new file mode 100644
index 00000000000..a42d64da458
--- /dev/null
+++ b/docs/src/content/en/reference/vNextWorkflows/dountil.mdx
@@ -0,0 +1,45 @@
+---
+title: "Reference: Workflow.dountil() | Building Workflows | Mastra Docs"
+description: Documentation for the `.dountil()` method in workflows, which creates a loop that executes a step until a condition is met.
+---
+
+# Workflow.dountil()
+
+The `.dountil()` method creates a loop that executes a step until a condition is met.
+
+## Usage
+
+```typescript
+workflow.dountil(stepOne, async ({ inputData }) => true);
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "step",
+      type: "Step",
+      description: "The step instance to execute in the loop",
+      isOptional: false,
+    },
+    {
+      name: "condition",
+      type: "(params : { inputData: any}) => Promise<boolean>",
+      description: "A function that returns a boolean indicating whether to continue the loop",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "workflow",
+      type: "NewWorkflow",
+      description: "The workflow instance for method chaining",
+    },
+  ]}
+/>
diff --git a/docs/src/content/en/reference/vNextWorkflows/dowhile.mdx b/docs/src/content/en/reference/vNextWorkflows/dowhile.mdx
new file mode 100644
index 00000000000..6b3849c9c9b
--- /dev/null
+++ b/docs/src/content/en/reference/vNextWorkflows/dowhile.mdx
@@ -0,0 +1,45 @@
+---
+title: "Reference: Workflow.dowhile() | Building Workflows | Mastra Docs"
+description: Documentation for the `.dowhile()` method in workflows, which creates a loop that executes a step while a condition is met.
+---
+
+# Workflow.dowhile()
+
+The `.dowhile()` method creates a loop that executes a step while a condition is met.
+
+## Usage
+
+```typescript
+workflow.dowhile(stepOne, async ({ inputData }) => true);
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "step",
+      type: "Step",
+      description: "The step instance to execute in the loop",
+      isOptional: false,
+    },
+    {
+      name: "condition",
+      type: "(params : { inputData: any}) => Promise<boolean>",
+      description: "A function that returns a boolean indicating whether to continue the loop",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "workflow",
+      type: "NewWorkflow",
+      description: "The workflow instance for method chaining",
+    },
+  ]}
+/>
diff --git a/docs/src/content/en/reference/vNextWorkflows/execute.mdx b/docs/src/content/en/reference/vNextWorkflows/execute.mdx
new file mode 100644
index 00000000000..5cf9c91072f
--- /dev/null
+++ b/docs/src/content/en/reference/vNextWorkflows/execute.mdx
@@ -0,0 +1,133 @@
+---
+title: "Reference: Workflow.execute() | Building Workflows | Mastra Docs"
+description: Documentation for the `.execute()` method in workflows, which executes a step with input data and returns the output.
+---
+
+# Workflow.execute()
+
+The `.execute()` method executes a step with input data and returns the output, allowing you to process data within a workflow.
+
+## Usage
+
+```typescript
+const myStep = createStep({
+  id: "my-step",
+  description: "Does something useful",
+  inputSchema: z.object({
+    inputValue: z.string(),
+  }),
+  outputSchema: z.object({
+    outputValue: z.string(),
+  }),
+  resumeSchema: z.object({
+    resumeValue: z.string(),
+  }),
+  suspendSchema: z.object({
+    suspendValue: z.string(),
+  }),
+  execute: async ({
+    inputData,
+    mastra,
+    getStepResult,
+    getInitData,
+    runtimeContext,
+  }) => {
+    const otherStepOutput = getStepResult(step2);
+    const initData = getInitData<typeof workflow>(); // typed as the workflow input schema
+    return {
+      outputValue: `Processed: ${inputData.inputValue}, ${initData.startValue} (runtimeContextValue: ${runtimeContext.get("runtimeContextValue")})`,
+    };
+  },
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "params",
+      type: "object",
+      description: "Configuration object for executing the step",
+      isOptional: false,
+      properties: [
+        {
+          name: "inputData",
+          type: "z.infer<TInput>",
+          description: "Input data matching the step's input schema",
+          isOptional: false,
+        },
+        {
+          name: "resumeData",
+          type: "ResumeSchema",
+          description: "Data for resuming a suspended step",
+          isOptional: true,
+        },
+        {
+          name: "suspend",
+          type: "(suspendPayload: any) => Promise<void>",
+          description: "Function to suspend step execution",
+          isOptional: false,
+        },
+        {
+          name: "resume",
+          type: "object",
+          description: "Configuration for resuming execution",
+          isOptional: true,
+          properties: [
+            {
+              name: "steps",
+              type: "string[]",
+              description: "Steps to resume",
+              isOptional: false
+            },
+            {
+              name: "resumePayload",
+              type: "any",
+              description: "Payload data for resuming",
+              isOptional: false
+            },
+            {
+              name: "runId",
+              type: "string",
+              description: "ID of the run to resume",
+              isOptional: true
+            }
+          ]
+        },
+        {
+          name: "emitter",
+          type: "object",
+          description: "Event emitter object",
+          isOptional: false,
+          properties: [
+            {
+              name: "emit",
+              type: "(event: string, data: any) => void",
+              description: "Function to emit events",
+              isOptional: false
+            }
+          ]
+        },
+        {
+          name: "mastra",
+          type: "Mastra",
+          description: "Mastra instance",
+          isOptional: false
+        }
+      ]
+    }
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "result",
+      type: "Promise<z.infer<TOutput>>",
+      description: "A promise that resolves to the output of the executed step",
+    },
+  ]}
+/>
diff --git a/docs/src/content/en/reference/vNextWorkflows/foreach.mdx b/docs/src/content/en/reference/vNextWorkflows/foreach.mdx
new file mode 100644
index 00000000000..d3b33f0a2c7
--- /dev/null
+++ b/docs/src/content/en/reference/vNextWorkflows/foreach.mdx
@@ -0,0 +1,53 @@
+---
+title: "Reference: Workflow.foreach() | Building Workflows | Mastra Docs"
+description: Documentation for the `.foreach()` method in workflows, which creates a loop that executes a step for each item in an array.
+---
+
+# Workflow.foreach()
+
+The `.foreach()` method creates a loop that executes a step for each item in an array.
+
+## Usage
+
+```typescript
+workflow.foreach(stepOne, { concurrency: 2 });
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "step",
+      type: "Step",
+      description: "The step instance to execute in the loop. The previous step must return an array type.",
+      isOptional: false,
+    },
+    {
+      name: "opts",
+      type: "object",
+      description: "Optional configuration for the loop. The concurrency option controls how many iterations can run in parallel (default: 1)",
+      isOptional: true,
+      properties: [
+        {
+          name: "concurrency",
+          type: "number",
+          description: "The number of concurrent iterations allowed (default: 1)",
+          isOptional: true,
+        },
+      ],
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "workflow",
+      type: "NewWorkflow",
+      description: "The workflow instance for method chaining",
+    },
+  ]}
+/>
diff --git a/docs/src/content/en/reference/vNextWorkflows/map.mdx b/docs/src/content/en/reference/vNextWorkflows/map.mdx
new file mode 100644
index 00000000000..eafe3572d04
--- /dev/null
+++ b/docs/src/content/en/reference/vNextWorkflows/map.mdx
@@ -0,0 +1,123 @@
+---
+title: "Reference: Workflow.map() | Building Workflows | Mastra Docs"
+description: Documentation for the `.map()` method in workflows, which maps output data from a previous step to the input of a subsequent step.
+---
+
+# Workflow.map()
+
+The `.map()` method maps output data from a previous step to the input of a subsequent step, allowing you to transform data between steps.
+
+## Usage
+
+```typescript
+const step1 = createStep({
+  id: "step1",
+  inputSchema: z.object({
+    inputValue: z.string(),
+  }),
+  outputSchema: z.object({
+    outputValue: z.string(),
+  }),
+  execute: async ({ inputData }) => {
+    return { outputValue: inputData.inputValue };
+  },
+});
+
+const step2 = createStep({
+  id: "step2",
+  inputSchema: z.object({
+    unexpectedName: z.string(),
+  }),
+  outputSchema: z.object({
+    result: z.string(),
+  }),
+  execute: async ({ inputData }) => {
+    return { result: inputData.unexpectedName };
+  },
+});
+
+const workflow = createWorkflow({
+  id: "my-workflow",
+  steps: [step1, step2],
+  inputSchema: z.object({
+    inputValue: z.string(),
+  }),
+  outputSchema: z.object({
+    result: z.string(),
+  }),
+});
+
+workflow
+  .then(step1)
+  .map({
+    unexpectedName: {
+      step: step1,
+      path: "outputValue",
+    },
+  })
+  .then(step2)
+  .commit();
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "mappingConfig",
+      type: "object",
+      description: "Configuration object that defines how data should be mapped between workflow steps, either as a mapping object or a mapping function",
+      isOptional: false,
+      properties: [
+        {
+          name: "step",
+          type: "Step | Step[]",
+          description: "The step(s) to map output from",
+          isOptional: true
+        },
+        {
+          name: "path", 
+          type: "string",
+          description: "Path to the output value in the step result",
+          isOptional: true
+        },
+        {
+          name: "value",
+          type: "any", 
+          description: "Static value to map",
+          isOptional: true
+        },
+        {
+          name: "schema",
+          type: "ZodType",
+          description: "Schema for validating the mapped value",
+          isOptional: true
+        },
+        {
+          name: "initData",
+          type: "Step",
+          description: "Step containing initial workflow data to map from",
+          isOptional: true
+        },
+        {
+          name: "runtimeContextPath",
+          type: "string",
+          description: "Path to value in runtime context",
+          isOptional: true
+        }
+      ]
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "workflow",
+      type: "NewWorkflow",
+      description: "The workflow instance for method chaining",
+    },
+  ]}
+/>
diff --git a/docs/src/content/en/reference/vNextWorkflows/parallel.mdx b/docs/src/content/en/reference/vNextWorkflows/parallel.mdx
new file mode 100644
index 00000000000..7d272f354bd
--- /dev/null
+++ b/docs/src/content/en/reference/vNextWorkflows/parallel.mdx
@@ -0,0 +1,39 @@
+---
+title: "Reference: Workflow.parallel() | Building Workflows | Mastra Docs"
+description: Documentation for the `.parallel()` method in workflows, which executes multiple steps in parallel.
+---
+
+# Workflow.parallel()
+
+The `.parallel()` method executes multiple steps in parallel.
+
+## Usage
+
+```typescript
+workflow.parallel([stepOne, stepTwo]);
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "steps",
+      type: "Step[]",
+      description: "The step instances to execute in parallel",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "workflow",
+      type: "NewWorkflow",
+      description: "The workflow instance for method chaining",
+    },
+  ]}
+/>
diff --git a/docs/src/content/en/reference/vNextWorkflows/resume.mdx b/docs/src/content/en/reference/vNextWorkflows/resume.mdx
new file mode 100644
index 00000000000..7be8dcd7e9d
--- /dev/null
+++ b/docs/src/content/en/reference/vNextWorkflows/resume.mdx
@@ -0,0 +1,67 @@
+---
+title: "Reference: Workflow.resume() | Building Workflows | Mastra Docs"
+description: Documentation for the `.resume()` method in workflows, which resumes a suspended workflow run with new data.
+---
+
+# Workflow.resume()
+
+The `.resume()` method resumes a suspended workflow run with new data, allowing you to continue execution from a specific step.
+
+## Usage
+
+```typescript
+const run = counterWorkflow.createRun();
+const result = await run.start({ inputData: { startValue: 0 } });
+
+if (result.status === "suspended") {
+  const resumedResults = await run.resume({
+    step: result.suspended[0],
+    resumeData: { newValue: 0 },
+  });
+}
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "params",
+      type: "object",
+      description: "Configuration object for resuming the workflow run",
+      isOptional: false,
+      properties: [
+        {
+          name: "resumeData",
+          type: "ResumeSchema",
+          description: "Data for resuming the suspended step",
+          isOptional: true,
+        },
+        {
+          name: "step",
+          type: "Step | Step[] | string | string[]",
+          description: "The step(s) to resume execution from",
+          isOptional: false,
+        },
+        {
+          name: "runtimeContext",
+          type: "RuntimeContext",
+          description: "Runtime context data to use when resuming",
+          isOptional: true,
+        }
+      ]
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "resumedResults",
+      type: "Promise<WorkflowResult<TOutput, TSteps>>",
+      description: "A promise that resolves to the result of the resumed workflow run",
+    },
+  ]}
+/>
diff --git a/docs/src/content/en/reference/vNextWorkflows/start.mdx b/docs/src/content/en/reference/vNextWorkflows/start.mdx
new file mode 100644
index 00000000000..bdf911b5116
--- /dev/null
+++ b/docs/src/content/en/reference/vNextWorkflows/start.mdx
@@ -0,0 +1,60 @@
+---
+title: "Reference: Workflow.start() | Building Workflows | Mastra Docs"
+description: Documentation for the `.start()` method in workflows, which starts a workflow run with input data.
+---
+
+# Workflow.start()
+
+The `.start()` method starts a workflow run with input data, allowing you to execute the workflow from the beginning.
+
+## Usage
+
+```typescript
+const run = myWorkflow.createRun();
+
+// Start the workflow with input data
+const result = await run.start({
+  inputData: {
+    startValue: "initial data",
+  },
+});
+```
+
+## Parameters
+<PropertiesTable
+  content={[
+    {
+      name: "params",
+      type: "object",
+      description: "Configuration object for starting the workflow run",
+      isOptional: false,
+      properties: [
+        {
+          name: "inputData",
+          type: "z.infer<TInput>",
+          description: "Input data matching the workflow's input schema",
+          isOptional: true,
+        },
+        {
+          name: "runtimeContext",
+          type: "RuntimeContext",
+          description: "Runtime context data to use when starting the workflow",
+          isOptional: true,
+        },
+      ],
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "result",
+      type: "Promise<WorkflowResult<TOutput, TSteps>>",
+      description: "A promise that resolves to the result of the workflow run",
+    },
+  ]}
+/>
+
diff --git a/docs/src/content/en/reference/vNextWorkflows/step.mdx b/docs/src/content/en/reference/vNextWorkflows/step.mdx
new file mode 100644
index 00000000000..96a1ec72371
--- /dev/null
+++ b/docs/src/content/en/reference/vNextWorkflows/step.mdx
@@ -0,0 +1,129 @@
+---
+title: "Reference: Step | Building Workflows | Mastra Docs"
+description: Documentation for the Step class, which defines individual units of work within a workflow.
+---
+
+# Step
+
+The Step class defines individual units of work within a workflow, encapsulating execution logic, data validation, and input/output handling.
+
+## Usage
+
+```typescript
+import { createStep } from "@mastra/core/workflows/vNext";
+import { z } from "zod";
+
+const processOrder = createStep({
+  id: "processOrder",
+  inputSchema: z.object({
+    orderId: z.string(),
+    userId: z.string(),
+  }),
+  outputSchema: z.object({
+    status: z.string(),
+    orderId: z.string(),
+  }),
+  resumeSchema: z.object({
+    orderId: z.string(),
+  }),
+  suspendSchema: z.object({}),
+  execute: async ({
+    inputData,
+    mastra,
+    getStepResult,
+    getInitData,
+    suspend,
+  }) => {
+    return {
+      status: "processed",
+      orderId: inputData.orderId,
+    };
+  },
+});
+```
+
+## Constructor Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "Unique identifier for the step",
+      required: true,
+    },
+    {
+      name: "description",
+      type: "string",
+      description: "Optional description of what the step does",
+      required: false,
+    },
+    {
+      name: "inputSchema",
+      type: "z.ZodType<any>",
+      description: "Zod schema defining the input structure",
+      required: true,
+    },
+    {
+      name: "outputSchema",
+      type: "z.ZodType<any>",
+      description: "Zod schema defining the output structure",
+      required: true,
+    },
+    {
+      name: "resumeSchema",
+      type: "z.ZodType<any>",
+      description: "Optional Zod schema for resuming the step",
+      required: false,
+    },
+    {
+      name: "suspendSchema",
+      type: "z.ZodType<any>",
+      description: "Optional Zod schema for suspending the step",
+      required: false,
+    },
+    {
+      name: "execute",
+      type: "(params: ExecuteParams) => Promise<any>",
+      description: "Async function containing step logic",
+      required: true,
+    },
+  ]}
+/>
+
+### ExecuteParams
+
+<PropertiesTable
+  content={[
+    {
+      name: "inputData",
+      type: "z.infer<TStepInput>",
+      description: "The input data matching the inputSchema",
+    },
+    {
+      name: "resumeData",
+      type: "z.infer<TResumeSchema>",
+      description: "The resume data matching the resumeSchema, when resuming the step from a suspended state. Only exists if the step is being resumed.",
+    },
+    {
+      name: "mastra",
+      type: "Mastra",
+      description: "Access to Mastra services (agents, tools, etc.)",
+    },
+    {
+      name: "getStepResult",
+      type: "(stepId: string) => any",
+      description: "Function to access results from other steps",
+    },
+    {
+      name: "getInitData",
+      type: "() => any",
+      description: "Function to access the initial input data of the workflow in any step",
+    },
+    {
+      name: "suspend",
+      type: "() => Promise<void>",
+      description: "Function to pause workflow execution",
+    },
+  ]}
+/>
diff --git a/docs/src/content/en/reference/vNextWorkflows/then.mdx b/docs/src/content/en/reference/vNextWorkflows/then.mdx
new file mode 100644
index 00000000000..3e00487dbf2
--- /dev/null
+++ b/docs/src/content/en/reference/vNextWorkflows/then.mdx
@@ -0,0 +1,39 @@
+---
+title: "Reference: Workflow.then() | Building Workflows | Mastra Docs"
+description: Documentation for the `.then()` method in workflows, which creates sequential dependencies between steps.
+---
+
+# Workflow.then()
+
+The `.then()` method creates a sequential dependency between workflow steps, ensuring steps execute in a specific order.
+
+## Usage
+
+```typescript
+workflow.then(stepOne).then(stepTwo);
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "step",
+      type: "Step",
+      description: "The step instance that should execute after the previous step completes",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "workflow",
+      type: "NewWorkflow",
+      description: "The workflow instance for method chaining",
+    },
+  ]}
+/>
diff --git a/docs/src/content/en/reference/vNextWorkflows/watch.mdx b/docs/src/content/en/reference/vNextWorkflows/watch.mdx
new file mode 100644
index 00000000000..66b3152c93f
--- /dev/null
+++ b/docs/src/content/en/reference/vNextWorkflows/watch.mdx
@@ -0,0 +1,47 @@
+---
+title: "Reference: Workflow.watch() | Building Workflows | Mastra Docs"
+description: Documentation for the `.watch()` method in workflows, which allows you to monitor the execution of a workflow run.
+---
+
+# Workflow.watch()
+
+The `.watch()` method allows you to monitor the execution of a workflow run, providing real-time updates on the status of steps.
+
+## Usage
+
+```typescript
+const run = myWorkflow.createRun();
+
+// Add a watcher to monitor execution
+run.watch(event => {
+  console.log('Step completed:', event.payload.currentStep.id);
+});
+
+// Start the workflow
+const result = await run.start({ inputData: {...} });
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "cb",
+      type: "(event: WatchEvent) => void",
+      description: "A callback function that is called whenever a step is completed or the workflow state changes",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "unwatch",
+      type: "() => void",
+      description: "A function that can be called to stop watching the workflow run",
+    },
+  ]}
+/>
diff --git a/docs/src/content/en/reference/vNextWorkflows/workflow.mdx b/docs/src/content/en/reference/vNextWorkflows/workflow.mdx
new file mode 100644
index 00000000000..f6595b2ff01
--- /dev/null
+++ b/docs/src/content/en/reference/vNextWorkflows/workflow.mdx
@@ -0,0 +1,155 @@
+---
+title: "Reference: Workflow Class | Building Workflows | Mastra Docs"
+description: Documentation for the Workflow class in Mastra, which enables you to create state machines for complex sequences of operations with conditional branching and data validation.
+---
+
+# Workflow Class
+
+The Workflow class enables you to create state machines for complex sequences of operations with conditional branching and data validation.
+
+## Usage
+
+```typescript
+const myWorkflow = createWorkflow({
+  id: "my-workflow",
+  inputSchema: z.object({
+    startValue: z.string(),
+  }),
+  outputSchema: z.object({
+    result: z.string(),
+  }),
+  steps: [step1, step2, step3], // Declare steps used in this workflow
+})
+  .then(step1)
+  .then(step2)
+  .then(step3)
+  .commit();
+
+const mastra = new Mastra({
+  vnext_workflows: {
+    myWorkflow,
+  },
+});
+
+const run = mastra.vnext_getWorkflow("myWorkflow").createRun();
+```
+
+## API Reference
+
+### Constructor
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "Unique identifier for the workflow",
+    },
+    {
+      name: "inputSchema",
+      type: "z.ZodType<any>",
+      description: "Zod schema defining the input structure for the workflow",
+    },
+    {
+      name: "outputSchema",
+      type: "z.ZodType<any>",
+      description: "Zod schema defining the output structure for the workflow",
+    },
+    {
+      name: "steps",
+      type: "Step[]",
+      description: "Array of steps to include in the workflow",
+    },
+  ]}
+/>
+
+### Core Methods
+
+#### `then()`
+
+Adds a step to the workflow sequentially. Returns the workflow instance for chaining.
+
+#### `parallel()`
+
+Executes multiple steps concurrently. Takes an array of steps and returns the workflow instance.
+
+#### `branch()`
+
+Creates conditional branching logic. Takes an array of tuples containing condition functions and steps to execute when conditions are met.
+
+#### `dowhile()`
+
+Creates a loop that executes a step repeatedly while a condition remains true. The condition is checked after each execution.
+
+#### `dountil()`
+
+Creates a loop that executes a step repeatedly until a condition becomes true. The condition is checked after each execution.
+
+#### `foreach()`
+
+Iterates over an array and executes a step for each element. Accepts optional concurrency configuration.
+
+#### `map()`
+
+Maps data between steps using either a mapping configuration object or a mapping function. Useful for transforming data between steps.
+
+#### `commit()`
+
+Validates and finalizes the workflow configuration. Must be called after adding all steps.
+
+#### `createRun()`
+
+Creates a new workflow run instance, allowing you to execute the workflow with specific input data. Accepts optional run ID.
+
+#### `execute()`
+
+Executes the workflow with provided input data. Handles workflow suspension, resumption and emits events during execution.
+
+
+## Workflow Status
+
+A workflow's status indicates its current execution state. The possible values are:
+
+<PropertiesTable
+  content={[
+    {
+      name: "success",
+      type: "string", 
+      description: "All steps finished executing successfully, with a valid result output",
+    },
+    {
+      name: "failed",
+      type: "string",
+      description: "Workflow encountered an error during execution, with error details available",
+    },
+    {
+      name: "suspended", 
+      type: "string",
+      description: "Workflow execution is paused waiting for resume, with suspended step information",
+    }
+  ]}
+/>
+
+## Passing Context Between Steps
+
+Steps can access data from previous steps in the workflow through the context object. Each step receives the accumulated context from all previous steps that have executed.
+
+```typescript
+workflow
+  .then({
+    id: "getData",
+    execute: async ({ inputData }) => {
+      return {
+        data: { id: "123", value: "example" },
+      };
+    },
+  })
+  .then({
+    id: "processData",
+    execute: async ({ inputData }) => {
+      // Access data from previous step through context.steps
+      const previousData = inputData.data;
+      // Process previousData.id and previousData.value
+    },
+  });
+```


Reviews:
user: login: greptile-apps[bot]
body: 
## PR Summary

This PR adds comprehensive documentation for the vNext Workflow API, focusing on suspend/resume functionality, control flow mechanisms, and API reference documentation.

- Added `/docs/src/content/en/reference/vNextWorkflows/` directory with detailed API reference for all workflow methods
- Enhanced `/docs/src/content/en/docs/workflows-vnext/suspend-and-resume.mdx` with clearer explanations and implementation-agnostic content
- Improved `/docs/src/content/en/docs/workflows-vnext/flow-control.mdx` with better code examples and data flow descriptions
- Added `/docs/src/content/en/reference/vNextWorkflows/_meta.ts` for API navigation structure
- Updated `/docs/src/content/en/docs/workflows-vnext/overview.mdx` with clearer workflow concepts and execution details

<sub>20 file(s) reviewed, 32 comment(s)</sub>
<sub>[Edit PR Review Bot Settings](https://app.greptile.com/review/github) | [Greptile](https://greptile.com?utm_source=greptile_expert&utm_medium=github&utm_campaign=code_reviews&utm_content=mastra_4291)</sub>
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-16T10:38:38Z
user: login: calcsam
body: Lgtm
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-05-16T12:57:32Z

Review comments:
diff_hunk: @@ -192,10 +199,12 @@ const planBothWorkflow = createWorkflow({
   }),
   steps: [planActivities, planIndoorActivities, sythesizeStep],
path: docs/src/content/en/docs/workflows-vnext/flow-control.mdx
user: login: greptile-apps[bot]
body: syntax: Typo in variable name 'sythesizeStep' should be 'synthesizeStep'

```suggestion
  steps: [planActivities, planIndoorActivities, synthesizeStep],
```
created_at: 2025-05-16T10:33:43Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,20 @@
+const meta = {
+    workflow: "Workflow",
+    step: "createStep()",
+    then: "then()",
+    parallel: "parallel()",
+    branch: "branch()",
+    dowhile: "dowhile()",
+    dountil: "dountil()",
+    foreach: "foreach()",
+    map: "map()",
+    commit: "commit()",
+    "create-run": "createRun()",
+    watch: "watch()",
+    execute: "execute()",
+    resume: "resume()",
+    start: "start()",
+  };
+  
+export default meta;
+  
path: docs/src/content/en/reference/vNextWorkflows/_meta.ts
user: login: greptile-apps[bot]
body: style: Extra empty line at end of file
created_at: 2025-05-16T10:34:13Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,26 @@
+---
+title: "Reference: Workflow.commit() | Building Workflows | Mastra Docs"
+description: Documentation for the `.commit()` method in workflows, which finalizes the workflow and returns the final result.
+---
+
+# Workflow.commit()
+
+The `.commit()` method finalizes the workflow and returns the final result.
+
+## Usage
+
+```typescript
+workflow.then(stepOne).commit();
path: docs/src/content/en/reference/vNextWorkflows/commit.mdx
user: login: greptile-apps[bot]
body: style: Example is too simplistic. Consider showing a more realistic workflow with multiple steps and configuration.
created_at: 2025-05-16T10:34:16Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,26 @@
+---
+title: "Reference: Workflow.commit() | Building Workflows | Mastra Docs"
+description: Documentation for the `.commit()` method in workflows, which finalizes the workflow and returns the final result.
+---
+
+# Workflow.commit()
+
+The `.commit()` method finalizes the workflow and returns the final result.
+
+## Usage
+
+```typescript
+workflow.then(stepOne).commit();
+```
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "workflow",
+      type: "NewWorkflow",
+      description: "The workflow instance for method chaining",
path: docs/src/content/en/reference/vNextWorkflows/commit.mdx
user: login: greptile-apps[bot]
body: logic: Description should clarify that this is the final workflow configuration, not for further chaining (which would be invalid after commit).

```suggestion
      description: "The final workflow configuration. Note: No further method chaining is possible after commit()",
```
created_at: 2025-05-16T10:34:16Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,60 @@
+---
+title: "Reference: Workflow.createRun() | Building Workflows | Mastra Docs"
+description: Documentation for the `.createRun()` method in workflows, which creates a new workflow run instance.
+---
+
+# Workflow.createRun()
+
+The `.createRun()` method creates a new workflow run instance, allowing you to execute the workflow with specific input data.
+
+## Usage
+
+```typescript
+const myWorkflow = createWorkflow({
+  id: "my-workflow",
+  inputSchema: z.object({
+    startValue: z.string(),
+  }),
+  outputSchema: z.object({
+    result: z.string(),
+  }),
+  steps: [step1, step2, step3], // Declare steps used in this workflow
+})
+  .then(step1)
+  .then(step2)
+  .then(step3)
+  .commit();
+
+const mastra = new Mastra({
+  vnext_workflows: {
+    myWorkflow,
+  },
+});
+
+const run = mastra.vnext_getWorkflow("myWorkflow").createRun();
+```
path: docs/src/content/en/reference/vNextWorkflows/create-run.mdx
user: login: greptile-apps[bot]
body: style: Missing import statements for `createWorkflow` and `z` in the example code. These are required dependencies shown in other docs.

```suggestion
import { createWorkflow } from '@mastra/core';
import { z } from 'zod';

const myWorkflow = createWorkflow({
  id: "my-workflow",
  inputSchema: z.object({
    startValue: z.string(),
  }),
  outputSchema: z.object({
    result: z.string(),
  }),
  steps: [step1, step2, step3], // Declare steps used in this workflow
})
  .then(step1)
  .then(step2)
  .then(step3)
  .commit();

const mastra = new Mastra({
  vnext_workflows: {
    myWorkflow,
  },
});

const run = mastra.vnext_getWorkflow("myWorkflow").createRun();
```
created_at: 2025-05-16T10:34:40Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,60 @@
+---
+title: "Reference: Workflow.createRun() | Building Workflows | Mastra Docs"
+description: Documentation for the `.createRun()` method in workflows, which creates a new workflow run instance.
+---
+
+# Workflow.createRun()
+
+The `.createRun()` method creates a new workflow run instance, allowing you to execute the workflow with specific input data.
+
+## Usage
+
+```typescript
+const myWorkflow = createWorkflow({
+  id: "my-workflow",
+  inputSchema: z.object({
+    startValue: z.string(),
+  }),
+  outputSchema: z.object({
+    result: z.string(),
+  }),
+  steps: [step1, step2, step3], // Declare steps used in this workflow
path: docs/src/content/en/reference/vNextWorkflows/create-run.mdx
user: login: greptile-apps[bot]
body: style: The comment references step1, step2, step3 but these steps are not defined in the example. Should show step definitions or remove the comment.
created_at: 2025-05-16T10:34:41Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,60 @@
+---
+title: "Reference: Workflow.createRun() | Building Workflows | Mastra Docs"
+description: Documentation for the `.createRun()` method in workflows, which creates a new workflow run instance.
+---
+
+# Workflow.createRun()
+
+The `.createRun()` method creates a new workflow run instance, allowing you to execute the workflow with specific input data.
+
+## Usage
+
+```typescript
+const myWorkflow = createWorkflow({
+  id: "my-workflow",
+  inputSchema: z.object({
+    startValue: z.string(),
+  }),
+  outputSchema: z.object({
+    result: z.string(),
+  }),
+  steps: [step1, step2, step3], // Declare steps used in this workflow
+})
+  .then(step1)
+  .then(step2)
+  .then(step3)
+  .commit();
+
+const mastra = new Mastra({
+  vnext_workflows: {
+    myWorkflow,
+  },
+});
+
+const run = mastra.vnext_getWorkflow("myWorkflow").createRun();
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "options",
+      type: "{ runId?: string }",
+      description: "Optional configuration for the run, including a custom run ID",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "run",
+      type: "Run",
+      description: "A new workflow run instance that can be used to execute the workflow",
path: docs/src/content/en/reference/vNextWorkflows/create-run.mdx
user: login: greptile-apps[bot]
body: style: Description should mention that the run instance needs to be started with `.start()` to execute the workflow, as shown in other docs.

```suggestion
      description: "A new workflow run instance that must be started with .start() to execute the workflow",
```
created_at: 2025-05-16T10:34:41Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,45 @@
+---
+title: "Reference: Workflow.dowhile() | Building Workflows | Mastra Docs"
+description: Documentation for the `.dowhile()` method in workflows, which creates a loop that executes a step while a condition is met.
+---
+
+# Workflow.dowhile()
+
+The `.dowhile()` method creates a loop that executes a step while a condition is met.
+
+## Usage
+
+```typescript
+workflow.dowhile(stepOne, async ({ context }) => true);
path: docs/src/content/en/reference/vNextWorkflows/dowhile.mdx
user: login: greptile-apps[bot]
body: logic: The usage example shows `{ context }` but the condition function signature doesn't match the actual API shown in flow-control.mdx which uses `{ inputData }`
created_at: 2025-05-16T10:35:06Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,45 @@
+---
+title: "Reference: Workflow.dowhile() | Building Workflows | Mastra Docs"
+description: Documentation for the `.dowhile()` method in workflows, which creates a loop that executes a step while a condition is met.
+---
+
+# Workflow.dowhile()
+
+The `.dowhile()` method creates a loop that executes a step while a condition is met.
+
+## Usage
+
+```typescript
+workflow.dowhile(stepOne, async ({ context }) => true);
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "step",
+      type: "Step",
+      description: "The step instance to execute in the loop",
+      isOptional: false,
+    },
+    {
+      name: "condition",
+      type: "() => boolean",
path: docs/src/content/en/reference/vNextWorkflows/dowhile.mdx
user: login: greptile-apps[bot]
body: logic: The condition type should be `(params: { inputData: any }) => Promise<boolean>` to match the actual API implementation shown in flow-control.mdx
created_at: 2025-05-16T10:35:07Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,45 @@
+---
+title: "Reference: Workflow.foreach() | Building Workflows | Mastra Docs"
+description: Documentation for the `.foreach()` method in workflows, which creates a loop that executes a step for each item in an array.
+---
+
+# Workflow.foreach()
+
+The `.foreach()` method creates a loop that executes a step for each item in an array.
+
+## Usage
+
+```typescript
+workflow.foreach(stepOne, { concurrency: 2 });
path: docs/src/content/en/reference/vNextWorkflows/foreach.mdx
user: login: greptile-apps[bot]
body: style: Example is too simplistic. Add a complete example showing input/output types and actual usage context.
created_at: 2025-05-16T10:35:18Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,45 @@
+---
+title: "Reference: Workflow.foreach() | Building Workflows | Mastra Docs"
+description: Documentation for the `.foreach()` method in workflows, which creates a loop that executes a step for each item in an array.
+---
+
+# Workflow.foreach()
+
+The `.foreach()` method creates a loop that executes a step for each item in an array.
+
+## Usage
+
+```typescript
+workflow.foreach(stepOne, { concurrency: 2 });
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "step",
+      type: "Step",
+      description: "The step instance to execute in the loop. The previous step must return an array type.",
+      isOptional: false,
+    },
+    {
+      name: "opts",
+      type: "{ concurrency: number }",
+      description: "Optional configuration for the loop, including the number of concurrent executions",
path: docs/src/content/en/reference/vNextWorkflows/foreach.mdx
user: login: greptile-apps[bot]
body: style: Description should explain what concurrency means in this context and its impact on execution.

```suggestion
      description: "Optional configuration for the loop. The concurrency option controls how many iterations can run in parallel (default: 1)",
```
created_at: 2025-05-16T10:35:19Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,45 @@
+---
+title: "Reference: Workflow.dountil() | Building Workflows | Mastra Docs"
+description: Documentation for the `.dountil()` method in workflows, which creates a loop that executes a step until a condition is met.
+---
+
+# Workflow.dountil()
+
+The `.dountil()` method creates a loop that executes a step until a condition is met.
+
+## Usage
+
+```typescript
+workflow.dountil(stepOne, async ({ context }) => true);
path: docs/src/content/en/reference/vNextWorkflows/dountil.mdx
user: login: greptile-apps[bot]
body: syntax: Example code uses incorrect parameter destructuring. Should be `({ inputData })` instead of `({ context })` to match the actual API.
created_at: 2025-05-16T10:35:24Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,45 @@
+---
+title: "Reference: Workflow.dountil() | Building Workflows | Mastra Docs"
+description: Documentation for the `.dountil()` method in workflows, which creates a loop that executes a step until a condition is met.
+---
+
+# Workflow.dountil()
+
+The `.dountil()` method creates a loop that executes a step until a condition is met.
+
+## Usage
+
+```typescript
+workflow.dountil(stepOne, async ({ context }) => true);
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "step",
+      type: "Step",
+      description: "The step instance to execute in the loop",
+      isOptional: false,
+    },
+    {
+      name: "condition",
+      type: "() => boolean",
+      description: "A function that returns a boolean indicating whether to continue the loop",
path: docs/src/content/en/reference/vNextWorkflows/dountil.mdx
user: login: greptile-apps[bot]
body: logic: Type and description are incorrect. Based on flow-control.mdx, should be `(params: { inputData: any }) => Promise<boolean>` and description should mention it receives the step's output as inputData.

```suggestion
      type: "(params: { inputData: any }) => Promise<boolean>",
      description: "A function that receives the step's output as inputData and returns a boolean indicating whether to continue the loop",
```
created_at: 2025-05-16T10:35:24Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,133 @@
+---
+title: "Reference: Workflow.execute() | Building Workflows | Mastra Docs"
+description: Documentation for the `.execute()` method in workflows, which executes a step with input data and returns the output.
+---
+
+# Workflow.execute()
+
+The `.execute()` method executes a step with input data and returns the output, allowing you to process data within a workflow.
+
+## Usage
+
+```typescript
+const myStep = createStep({
+  id: "my-step",
+  description: "Does something useful",
+  inputSchema: z.object({
+    inputValue: z.string(),
+  }),
+  outputSchema: z.object({
+    outputValue: z.string(),
+  }),
+  resumeSchema: z.object({
+    resumeValue: z.string(),
+  }),
+  suspendSchema: z.object({
+    suspendValue: z.string(),
+  }),
+  execute: async ({
+    inputData,
+    mastra,
+    getStepResult,
+    getInitData,
+    runtimeContext,
+  }) => {
+    const otherStepOutput = getStepResult(step2);
path: docs/src/content/en/reference/vNextWorkflows/execute.mdx
user: login: greptile-apps[bot]
body: logic: step2 is undefined in this example. Either define it or use a different example that doesn't reference undefined variables.
created_at: 2025-05-16T10:35:52Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,133 @@
+---
+title: "Reference: Workflow.execute() | Building Workflows | Mastra Docs"
+description: Documentation for the `.execute()` method in workflows, which executes a step with input data and returns the output.
+---
+
+# Workflow.execute()
+
+The `.execute()` method executes a step with input data and returns the output, allowing you to process data within a workflow.
+
+## Usage
+
+```typescript
+const myStep = createStep({
+  id: "my-step",
+  description: "Does something useful",
+  inputSchema: z.object({
+    inputValue: z.string(),
+  }),
+  outputSchema: z.object({
+    outputValue: z.string(),
+  }),
+  resumeSchema: z.object({
+    resumeValue: z.string(),
+  }),
+  suspendSchema: z.object({
+    suspendValue: z.string(),
+  }),
+  execute: async ({
+    inputData,
+    mastra,
+    getStepResult,
+    getInitData,
+    runtimeContext,
+  }) => {
+    const otherStepOutput = getStepResult(step2);
+    const initData = getInitData<typeof workflow>(); // typed as the workflow input schema
path: docs/src/content/en/reference/vNextWorkflows/execute.mdx
user: login: greptile-apps[bot]
body: logic: workflow is undefined in this example. Either define it or remove the type reference.
created_at: 2025-05-16T10:35:52Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,133 @@
+---
+title: "Reference: Workflow.execute() | Building Workflows | Mastra Docs"
+description: Documentation for the `.execute()` method in workflows, which executes a step with input data and returns the output.
+---
+
+# Workflow.execute()
+
+The `.execute()` method executes a step with input data and returns the output, allowing you to process data within a workflow.
+
+## Usage
+
+```typescript
+const myStep = createStep({
+  id: "my-step",
+  description: "Does something useful",
+  inputSchema: z.object({
+    inputValue: z.string(),
+  }),
+  outputSchema: z.object({
+    outputValue: z.string(),
+  }),
+  resumeSchema: z.object({
+    resumeValue: z.string(),
+  }),
+  suspendSchema: z.object({
+    suspendValue: z.string(),
+  }),
+  execute: async ({
+    inputData,
+    mastra,
+    getStepResult,
+    getInitData,
+    runtimeContext,
+  }) => {
+    const otherStepOutput = getStepResult(step2);
+    const initData = getInitData<typeof workflow>(); // typed as the workflow input schema
+    return {
+      outputValue: `Processed: ${inputData.inputValue}, ${initData.startValue} (runtimeContextValue: ${runtimeContext.get("runtimeContextValue")})`,
+    };
+  },
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "params",
+      type: "object",
+      description: "Configuration object for executing the step",
+      isOptional: false,
+      properties: [
+        {
+          name: "inputData",
+          type: "z.infer<TInput>",
+          description: "Input data matching the step's input schema",
+          isOptional: false,
+        },
+        {
+          name: "resumeData",
+          type: "ResumeSchema",
+          description: "Data for resuming a suspended step",
+          isOptional: true,
+        },
+        {
+          name: "suspend",
+          type: "(suspendPayload: any) => Promise<void>",
+          description: "Function to suspend step execution",
+          isOptional: false,
+        },
+        {
+          name: "resume",
+          type: "object",
+          description: "Configuration for resuming execution",
+          isOptional: true,
+          properties: [
+            {
+              name: "steps",
+              type: "string[]",
+              description: "Steps to resume",
+              isOptional: false
+            },
+            {
+              name: "resumePayload",
+              type: "any",
+              description: "Payload data for resuming",
+              isOptional: false
+            },
+            {
+              name: "runId",
+              type: "string",
+              description: "ID of the run to resume",
+              isOptional: true
+            }
+          ]
+        },
+        {
+          name: "emitter",
+          type: "object",
+          description: "Event emitter object",
+          isOptional: false,
+          properties: [
+            {
+              name: "emit",
+              type: "(event: string, data: any) => void",
+              description: "Function to emit events",
+              isOptional: false
+            }
+          ]
+        },
+        {
+          name: "mastra",
+          type: "Mastra",
+          description: "Mastra instance",
+          isOptional: false
+        }
+      ]
+    }
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "result",
+      type: "Promise",
path: docs/src/content/en/reference/vNextWorkflows/execute.mdx
user: login: greptile-apps[bot]
body: style: Promise type should include the generic type parameter for better type information, e.g. Promise&lt;TOutput&gt;

```suggestion
      type: "Promise<TOutput>",
```
created_at: 2025-05-16T10:35:53Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,67 @@
+---
+title: "Reference: Workflow.resume() | Building Workflows | Mastra Docs"
+description: Documentation for the `.resume()` method in workflows, which resumes a suspended workflow run with new data.
+---
+
+# Workflow.resume()
+
+The `.resume()` method resumes a suspended workflow run with new data, allowing you to continue execution from a specific step.
+
+## Usage
+
+```typescript
+const run = counterWorkflow.createRun();
+const result = await run.start({ inputData: { startValue: 0 } });
path: docs/src/content/en/reference/vNextWorkflows/resume.mdx
user: login: greptile-apps[bot]
body: style: Example uses undeclared `counterWorkflow`. Should use `myWorkflow` to match other docs or explain what `counterWorkflow` is.
created_at: 2025-05-16T10:36:00Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,67 @@
+---
+title: "Reference: Workflow.resume() | Building Workflows | Mastra Docs"
+description: Documentation for the `.resume()` method in workflows, which resumes a suspended workflow run with new data.
+---
+
+# Workflow.resume()
+
+The `.resume()` method resumes a suspended workflow run with new data, allowing you to continue execution from a specific step.
+
+## Usage
+
+```typescript
+const run = counterWorkflow.createRun();
+const result = await run.start({ inputData: { startValue: 0 } });
+
+if (result.status === "suspended") {
+  const resumedResults = await run.resume({
+    step: result.suspended[0],
+    resumeData: { newValue: 0 },
path: docs/src/content/en/reference/vNextWorkflows/resume.mdx
user: login: greptile-apps[bot]
body: logic: Example's `newValue` doesn't match any schema shown. Should match the `ResumeSchema` type mentioned in parameters.
created_at: 2025-05-16T10:36:01Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,39 @@
+---
+title: "Reference: Workflow.parallel() | Building Workflows | Mastra Docs"
+description: Documentation for the `.parallel()` method in workflows, which executes multiple steps in parallel.
+---
+
+# Workflow.parallel()
+
+The `.parallel()` method executes multiple steps in parallel.
+
+## Usage
+
+```typescript
+workflow.parallel([stepOne, stepTwo]);
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "steps",
+      type: "Step[]",
+      description: "The step instances to execute in parallel",
path: docs/src/content/en/reference/vNextWorkflows/parallel.mdx
user: login: greptile-apps[bot]
body: style: Description should mention that steps can include both individual steps and nested workflows, as shown in flow-control.mdx

```suggestion
      description: "The step instances or nested workflows to execute in parallel",
```
created_at: 2025-05-16T10:36:32Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,60 @@
+---
+title: "Reference: Workflow.start() | Building Workflows | Mastra Docs"
+description: Documentation for the `.start()` method in workflows, which starts a workflow run with input data.
+---
+
+# Workflow.start()
+
+The `.start()` method starts a workflow run with input data, allowing you to execute the workflow from the beginning.
+
+## Usage
+
+```typescript
+const run = myWorkflow.createRun();
+
+// Start the workflow with input data
+const result = await run.start({
+  inputData: {
+    startValue: "initial data",
+  },
+});
+```
+
+## Parameters
+<PropertiesTable
+  content={[
+    {
+      name: "params",
+      type: "object",
+      description: "Configuration object for starting the workflow run",
+      isOptional: false,
+      properties: [
+        {
+          name: "inputData",
+          type: "z.infer<TInput>",
+          description: "Input data matching the workflow's input schema",
+          isOptional: true,
+        },
path: docs/src/content/en/reference/vNextWorkflows/start.mdx
user: login: greptile-apps[bot]
body: logic: inputData is marked as optional (isOptional: true) but the params object is required (isOptional: false). This seems inconsistent with the usage example where inputData is always provided
created_at: 2025-05-16T10:36:32Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,123 @@
+---
+title: "Reference: Workflow.map() | Building Workflows | Mastra Docs"
+description: Documentation for the `.map()` method in workflows, which maps output data from a previous step to the input of a subsequent step.
+---
+
+# Workflow.map()
+
+The `.map()` method maps output data from a previous step to the input of a subsequent step, allowing you to transform data between steps.
+
+## Usage
+
+```typescript
+const step1 = createStep({
+  id: "step1",
+  inputSchema: z.object({
+    inputValue: z.string(),
+  }),
+  outputSchema: z.object({
+    outputValue: z.string(),
+  }),
+  execute: async ({ inputData }) => {
+    return { outputValue: inputData.inputValue };
+  },
+});
+
+const step2 = createStep({
+  id: "step2",
+  inputSchema: z.object({
+    unexpectedName: z.string(),
+  }),
+  outputSchema: z.object({
+    result: z.string(),
+  }),
+  execute: async ({ inputData }) => {
+    return { result: inputData.outputValue };
+  },
path: docs/src/content/en/reference/vNextWorkflows/map.mdx
user: login: greptile-apps[bot]
body: logic: step2's execute function references inputData.outputValue but the input schema defines unexpectedName. This will cause a runtime error.

```suggestion
  execute: async ({ inputData }) => {
    return { result: inputData.unexpectedName };
  },
```
created_at: 2025-05-16T10:36:32Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,123 @@
+---
+title: "Reference: Workflow.map() | Building Workflows | Mastra Docs"
+description: Documentation for the `.map()` method in workflows, which maps output data from a previous step to the input of a subsequent step.
+---
+
+# Workflow.map()
+
+The `.map()` method maps output data from a previous step to the input of a subsequent step, allowing you to transform data between steps.
+
+## Usage
+
+```typescript
+const step1 = createStep({
+  id: "step1",
+  inputSchema: z.object({
+    inputValue: z.string(),
+  }),
+  outputSchema: z.object({
+    outputValue: z.string(),
+  }),
+  execute: async ({ inputData }) => {
+    return { outputValue: inputData.inputValue };
+  },
+});
+
+const step2 = createStep({
+  id: "step2",
+  inputSchema: z.object({
+    unexpectedName: z.string(),
+  }),
+  outputSchema: z.object({
+    result: z.string(),
+  }),
+  execute: async ({ inputData }) => {
+    return { result: inputData.outputValue };
+  },
+});
+
+const workflow = createWorkflow({
+  id: "my-workflow",
+  steps: [step1, step2],
+  inputSchema: z.object({
+    inputValue: z.string(),
+  }),
+  outputSchema: z.object({
+    result: z.string(),
+  }),
+});
+
+workflow
+  .then(step1)
+  .map({
+    unexpectedName: {
+      step: step1,
+      path: "outputValue",
+    },
+  })
+  .then(step2)
+  .commit();
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "mappingConfig",
+      type: "object",
+      description: "Configuration object that defines how data should be mapped between workflow steps, either as a mapping object or a mapping function",
+      isOptional: false,
path: docs/src/content/en/reference/vNextWorkflows/map.mdx
user: login: greptile-apps[bot]
body: syntax: The description mentions 'mapping function' but the type only shows 'object'. The type should be '(context: MappingContext) =&gt; object | object'
created_at: 2025-05-16T10:36:33Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,123 @@
+---
+title: "Reference: Workflow.map() | Building Workflows | Mastra Docs"
+description: Documentation for the `.map()` method in workflows, which maps output data from a previous step to the input of a subsequent step.
+---
+
+# Workflow.map()
+
+The `.map()` method maps output data from a previous step to the input of a subsequent step, allowing you to transform data between steps.
+
+## Usage
+
+```typescript
+const step1 = createStep({
+  id: "step1",
+  inputSchema: z.object({
+    inputValue: z.string(),
+  }),
+  outputSchema: z.object({
+    outputValue: z.string(),
+  }),
+  execute: async ({ inputData }) => {
+    return { outputValue: inputData.inputValue };
+  },
+});
+
+const step2 = createStep({
+  id: "step2",
+  inputSchema: z.object({
+    unexpectedName: z.string(),
+  }),
+  outputSchema: z.object({
+    result: z.string(),
+  }),
+  execute: async ({ inputData }) => {
+    return { result: inputData.outputValue };
+  },
+});
+
+const workflow = createWorkflow({
+  id: "my-workflow",
+  steps: [step1, step2],
+  inputSchema: z.object({
+    inputValue: z.string(),
+  }),
+  outputSchema: z.object({
+    result: z.string(),
+  }),
+});
+
+workflow
+  .then(step1)
+  .map({
+    unexpectedName: {
+      step: step1,
+      path: "outputValue",
+    },
+  })
+  .then(step2)
+  .commit();
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "mappingConfig",
+      type: "object",
+      description: "Configuration object that defines how data should be mapped between workflow steps, either as a mapping object or a mapping function",
+      isOptional: false,
+      properties: [
+        {
+          name: "step",
+          type: "Step | Step[]",
+          description: "The step(s) to map output from",
+          isOptional: true
+        },
+        {
+          name: "path", 
+          type: "string",
+          description: "Path to the output value in the step result",
+          isOptional: true
+        },
+        {
+          name: "value",
+          type: "any", 
+          description: "Static value to map",
+          isOptional: true
+        },
+        {
+          name: "schema",
+          type: "ZodType",
+          description: "Schema for validating the mapped value",
+          isOptional: true
+        },
+        {
+          name: "initData",
+          type: "Step",
+          description: "Step containing initial workflow data to map from",
+          isOptional: true
+        },
path: docs/src/content/en/reference/vNextWorkflows/map.mdx
user: login: greptile-apps[bot]
body: syntax: initData is documented as type 'Step' but should be 'string' to reference the initial workflow data
created_at: 2025-05-16T10:36:33Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,129 @@
+---
+title: "Reference: Step | Building Workflows | Mastra Docs"
+description: Documentation for the Step class, which defines individual units of work within a workflow.
+---
+
+# Step
+
+The Step class defines individual units of work within a workflow, encapsulating execution logic, data validation, and input/output handling.
+
+## Usage
+
+```typescript
+import { createStep } from "@mastra/core/workflows/vNext";
+import { z } from "zod";
+
+const processOrder = createStep({
+  id: "processOrder",
+  inputSchema: z.object({
+    orderId: z.string(),
+    userId: z.string(),
+  }),
+  outputSchema: z.object({
+    status: z.string(),
+    orderId: z.string(),
+  }),
+  resumeSchema: z.object({
+    orderId: z.string(),
+  }),
+  suspendSchema: z.object({}),
+  execute: async ({
+    inputData,
+    mastra,
+    getStepResult,
+    getInitData,
+    runtimeContext,
+  }) => {
path: docs/src/content/en/reference/vNextWorkflows/step.mdx
user: login: greptile-apps[bot]
body: logic: The example shows `runtimeContext` in the parameters but it's not documented in the ExecuteParams table below
created_at: 2025-05-16T10:36:43Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,129 @@
+---
+title: "Reference: Step | Building Workflows | Mastra Docs"
+description: Documentation for the Step class, which defines individual units of work within a workflow.
+---
+
+# Step
+
+The Step class defines individual units of work within a workflow, encapsulating execution logic, data validation, and input/output handling.
+
+## Usage
+
+```typescript
+import { createStep } from "@mastra/core/workflows/vNext";
+import { z } from "zod";
+
+const processOrder = createStep({
+  id: "processOrder",
+  inputSchema: z.object({
+    orderId: z.string(),
+    userId: z.string(),
+  }),
+  outputSchema: z.object({
+    status: z.string(),
+    orderId: z.string(),
+  }),
+  resumeSchema: z.object({
+    orderId: z.string(),
+  }),
+  suspendSchema: z.object({}),
+  execute: async ({
+    inputData,
+    mastra,
+    getStepResult,
+    getInitData,
+    runtimeContext,
+  }) => {
+    return {
+      status: "processed",
+      orderId: inputData.orderId,
+    };
+  },
+});
+```
+
+## Constructor Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "Unique identifier for the step",
+      required: true,
+    },
+    {
+      name: "description",
+      type: "string",
+      description: "Optional description of what the step does",
+      required: false,
+    },
+    {
+      name: "inputSchema",
+      type: "z.ZodType<any>",
+      description: "Zod schema defining the input structure",
+      required: true,
+    },
+    {
+      name: "outputSchema",
+      type: "z.ZodType<any>",
+      description: "Zod schema defining the output structure",
+      required: true,
+    },
+    {
+      name: "resumeSchema",
+      type: "z.ZodType<any>",
+      description: "Optional Zod schema for resuming the step",
+      required: false,
+    },
+    {
+      name: "suspendSchema",
+      type: "z.ZodType<any>",
+      description: "Optional Zod schema for suspending the step",
+      required: false,
+    },
+    {
+      name: "execute",
+      type: "(params: ExecuteParams) => Promise<any>",
+      description: "Async function containing step logic",
+      required: true,
+    },
+  ]}
+/>
+
+### ExecuteParams
+
+<PropertiesTable
+  content={[
+    {
+      name: "inputData",
+      type: "z.infer<TStepInput>",
+      description: "The input data matching the inputSchema",
+    },
+    {
+      name: "resumeData",
+      type: "z.infer<TResumeSchema>",
+      description: "The resume data matching the resumeSchema, when resuming the step from a suspended state. Only exists if the step is being resumed.",
+    },
+    {
+      name: "mastra",
+      type: "Mastra",
+      description: "Access to Mastra services (agents, tools, etc.)",
+    },
+    {
+      name: "getStepResult",
+      type: "(stepId: string) => any",
path: docs/src/content/en/reference/vNextWorkflows/step.mdx
user: login: greptile-apps[bot]
body: style: Return type should be properly typed as `<TOutput>` instead of `any` for type safety

```suggestion
      type: "(stepId: string) => Promise<TOutput>",
```
created_at: 2025-05-16T10:36:43Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,129 @@
+---
+title: "Reference: Step | Building Workflows | Mastra Docs"
+description: Documentation for the Step class, which defines individual units of work within a workflow.
+---
+
+# Step
+
+The Step class defines individual units of work within a workflow, encapsulating execution logic, data validation, and input/output handling.
+
+## Usage
+
+```typescript
+import { createStep } from "@mastra/core/workflows/vNext";
+import { z } from "zod";
+
+const processOrder = createStep({
+  id: "processOrder",
+  inputSchema: z.object({
+    orderId: z.string(),
+    userId: z.string(),
+  }),
+  outputSchema: z.object({
+    status: z.string(),
+    orderId: z.string(),
+  }),
+  resumeSchema: z.object({
+    orderId: z.string(),
+  }),
+  suspendSchema: z.object({}),
+  execute: async ({
+    inputData,
+    mastra,
+    getStepResult,
+    getInitData,
+    runtimeContext,
+  }) => {
+    return {
+      status: "processed",
+      orderId: inputData.orderId,
+    };
+  },
+});
+```
+
+## Constructor Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "Unique identifier for the step",
+      required: true,
+    },
+    {
+      name: "description",
+      type: "string",
+      description: "Optional description of what the step does",
+      required: false,
+    },
+    {
+      name: "inputSchema",
+      type: "z.ZodType<any>",
+      description: "Zod schema defining the input structure",
+      required: true,
+    },
+    {
+      name: "outputSchema",
+      type: "z.ZodType<any>",
+      description: "Zod schema defining the output structure",
+      required: true,
+    },
+    {
+      name: "resumeSchema",
+      type: "z.ZodType<any>",
+      description: "Optional Zod schema for resuming the step",
+      required: false,
+    },
+    {
+      name: "suspendSchema",
+      type: "z.ZodType<any>",
+      description: "Optional Zod schema for suspending the step",
+      required: false,
+    },
+    {
+      name: "execute",
+      type: "(params: ExecuteParams) => Promise<any>",
+      description: "Async function containing step logic",
+      required: true,
+    },
+  ]}
+/>
+
+### ExecuteParams
+
+<PropertiesTable
+  content={[
+    {
+      name: "inputData",
+      type: "z.infer<TStepInput>",
+      description: "The input data matching the inputSchema",
+    },
+    {
+      name: "resumeData",
+      type: "z.infer<TResumeSchema>",
+      description: "The resume data matching the resumeSchema, when resuming the step from a suspended state. Only exists if the step is being resumed.",
+    },
+    {
+      name: "mastra",
+      type: "Mastra",
+      description: "Access to Mastra services (agents, tools, etc.)",
+    },
+    {
+      name: "getStepResult",
+      type: "(stepId: string) => any",
+      description: "Function to access results from other steps",
+    },
+    {
+      name: "getInitData",
+      type: "() => any",
path: docs/src/content/en/reference/vNextWorkflows/step.mdx
user: login: greptile-apps[bot]
body: style: Return type should be properly typed as `<TWorkflowInput>` instead of `any` for type safety

```suggestion
      type: "() => TWorkflowInput",
```
created_at: 2025-05-16T10:36:44Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,129 @@
+---
+title: "Reference: Step | Building Workflows | Mastra Docs"
+description: Documentation for the Step class, which defines individual units of work within a workflow.
+---
+
+# Step
+
+The Step class defines individual units of work within a workflow, encapsulating execution logic, data validation, and input/output handling.
+
+## Usage
+
+```typescript
+import { createStep } from "@mastra/core/workflows/vNext";
+import { z } from "zod";
+
+const processOrder = createStep({
+  id: "processOrder",
+  inputSchema: z.object({
+    orderId: z.string(),
+    userId: z.string(),
+  }),
+  outputSchema: z.object({
+    status: z.string(),
+    orderId: z.string(),
+  }),
+  resumeSchema: z.object({
+    orderId: z.string(),
+  }),
+  suspendSchema: z.object({}),
+  execute: async ({
+    inputData,
+    mastra,
+    getStepResult,
+    getInitData,
+    runtimeContext,
+  }) => {
+    return {
+      status: "processed",
+      orderId: inputData.orderId,
+    };
+  },
+});
+```
+
+## Constructor Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "Unique identifier for the step",
+      required: true,
+    },
+    {
+      name: "description",
+      type: "string",
+      description: "Optional description of what the step does",
+      required: false,
+    },
+    {
+      name: "inputSchema",
+      type: "z.ZodType<any>",
+      description: "Zod schema defining the input structure",
+      required: true,
+    },
+    {
+      name: "outputSchema",
+      type: "z.ZodType<any>",
+      description: "Zod schema defining the output structure",
+      required: true,
+    },
+    {
+      name: "resumeSchema",
+      type: "z.ZodType<any>",
+      description: "Optional Zod schema for resuming the step",
+      required: false,
+    },
+    {
+      name: "suspendSchema",
+      type: "z.ZodType<any>",
+      description: "Optional Zod schema for suspending the step",
+      required: false,
+    },
+    {
+      name: "execute",
+      type: "(params: ExecuteParams) => Promise<any>",
path: docs/src/content/en/reference/vNextWorkflows/step.mdx
user: login: greptile-apps[bot]
body: style: Return type should be `Promise<TOutput>` instead of `Promise<any>` for better type safety

```suggestion
      type: "(params: ExecuteParams) => Promise<TOutput>",
```
created_at: 2025-05-16T10:36:44Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,47 @@
+---
+title: "Reference: Workflow.watch() | Building Workflows | Mastra Docs"
+description: Documentation for the `.watch()` method in workflows, which allows you to monitor the execution of a workflow run.
+---
+
+# Workflow.watch()
+
+The `.watch()` method allows you to monitor the execution of a workflow run, providing real-time updates on the status of steps.
+
+## Usage
+
+```typescript
+const run = myWorkflow.createRun();
+
+// Add a watcher to monitor execution
+run.watch(event => {
+  console.log('Step completed:', event.payload.currentStep.id);
path: docs/src/content/en/reference/vNextWorkflows/watch.mdx
user: login: greptile-apps[bot]
body: style: Example only shows currentStep.id but ignores other important fields like status and output that are available in the event payload
created_at: 2025-05-16T10:37:18Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,47 @@
+---
+title: "Reference: Workflow.watch() | Building Workflows | Mastra Docs"
+description: Documentation for the `.watch()` method in workflows, which allows you to monitor the execution of a workflow run.
+---
+
+# Workflow.watch()
+
+The `.watch()` method allows you to monitor the execution of a workflow run, providing real-time updates on the status of steps.
+
+## Usage
+
+```typescript
+const run = myWorkflow.createRun();
+
+// Add a watcher to monitor execution
+run.watch(event => {
+  console.log('Step completed:', event.payload.currentStep.id);
+});
+
+// Start the workflow
+const result = await run.start({ inputData: {...} });
path: docs/src/content/en/reference/vNextWorkflows/watch.mdx
user: login: greptile-apps[bot]
body: style: Example uses {...} for inputData which isn't helpful - should show a concrete example matching the overview docs
created_at: 2025-05-16T10:37:18Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,155 @@
+---
+title: "Reference: Workflow Class | Building Workflows | Mastra Docs"
+description: Documentation for the Workflow class in Mastra, which enables you to create state machines for complex sequences of operations with conditional branching and data validation.
+---
+
+# Workflow Class
+
+The Workflow class enables you to create state machines for complex sequences of operations with conditional branching and data validation.
+
+## Usage
+
+```typescript
+const myWorkflow = createWorkflow({
+  id: "my-workflow",
+  inputSchema: z.object({
+    startValue: z.string(),
+  }),
+  outputSchema: z.object({
+    result: z.string(),
+  }),
+  steps: [step1, step2, step3], // Declare steps used in this workflow
+})
+  .then(step1)
+  .then(step2)
+  .then(step3)
+  .commit();
+
+const mastra = new Mastra({
+  vnext_workflows: {
+    myWorkflow,
+  },
+});
+
+const run = mastra.vnext_getWorkflow("myWorkflow").createRun();
+```
+
+## API Reference
+
+### Constructor
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description: "Unique identifier for the workflow",
+    },
+    {
+      name: "inputSchema",
+      type: "z.ZodType<any>",
+      description: "Zod schema defining the input structure for the workflow",
+    },
+    {
+      name: "outputSchema",
+      type: "z.ZodType<any>",
+      description: "Zod schema defining the output structure for the workflow",
+    },
+    {
+      name: "steps",
+      type: "Step[]",
+      description: "Array of steps to include in the workflow",
+    },
+  ]}
+/>
+
+### Core Methods
+
+#### `then()`
+
+Adds a step to the workflow sequentially. Returns the workflow instance for chaining.
+
+#### `parallel()`
+
+Executes multiple steps concurrently. Takes an array of steps and returns the workflow instance.
+
+#### `branch()`
+
+Creates conditional branching logic. Takes an array of tuples containing condition functions and steps to execute when conditions are met.
+
+#### `dowhile()`
+
+Creates a loop that executes a step repeatedly while a condition remains true. The condition is checked after each execution.
+
+#### `dountil()`
+
+Creates a loop that executes a step repeatedly until a condition becomes true. The condition is checked after each execution.
+
+#### `foreach()`
+
+Iterates over an array and executes a step for each element. Accepts optional concurrency configuration.
+
+#### `map()`
+
+Maps data between steps using either a mapping configuration object or a mapping function. Useful for transforming data between steps.
+
+#### `commit()`
+
+Validates and finalizes the workflow configuration. Must be called after adding all steps.
+
+#### `createRun()`
+
+Creates a new workflow run instance, allowing you to execute the workflow with specific input data. Accepts optional run ID.
+
+#### `execute()`
+
+Executes the workflow with provided input data. Handles workflow suspension, resumption and emits events during execution.
+
+
+## Workflow Status
+
+A workflow's status indicates its current execution state. The possible values are:
+
+<PropertiesTable
+  content={[
+    {
+      name: "success",
+      type: "string", 
+      description: "All steps finished executing successfully, with a valid result output",
+    },
+    {
+      name: "failed",
+      type: "string",
+      description: "Workflow encountered an error during execution, with error details available",
+    },
+    {
+      name: "suspended", 
+      type: "string",
+      description: "Workflow execution is paused waiting for resume, with suspended step information",
+    }
+  ]}
+/>
+
+## Passing Context Between Steps
+
+Steps can access data from previous steps in the workflow through the context object. Each step receives the accumulated context from all previous steps that have executed.
+
+```typescript
+workflow
+  .then({
+    id: "getData",
+    execute: async ({ inputData }) => {
+      return {
+        data: { id: "123", value: "example" },
+      };
+    },
+  })
+  .then({
+    id: "processData",
+    execute: async ({ inputData }) => {
+      // Access data from previous step through context.steps
+      const previousData = inputData.data;
path: docs/src/content/en/reference/vNextWorkflows/workflow.mdx
user: login: greptile-apps[bot]
body: logic: Incorrect context access pattern shown. Should be `getStepResult('getData').data` instead of `inputData.data`
created_at: 2025-05-16T10:37:31Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,39 @@
+---
+title: "Reference: Workflow.then() | Building Workflows | Mastra Docs"
+description: Documentation for the `.then()` method in workflows, which creates sequential dependencies between steps.
+---
+
+# Workflow.then()
+
+The `.then()` method creates a sequential dependency between workflow steps, ensuring steps execute in a specific order.
+
+## Usage
+
+```typescript
+workflow.then(stepOne).then(stepTwo);
path: docs/src/content/en/reference/vNextWorkflows/then.mdx
user: login: greptile-apps[bot]
body: style: Example could be more realistic by showing input/output schema matching between steps
created_at: 2025-05-16T10:37:44Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,39 @@
+---
+title: "Reference: Workflow.then() | Building Workflows | Mastra Docs"
+description: Documentation for the `.then()` method in workflows, which creates sequential dependencies between steps.
+---
+
+# Workflow.then()
+
+The `.then()` method creates a sequential dependency between workflow steps, ensuring steps execute in a specific order.
+
+## Usage
+
+```typescript
+workflow.then(stepOne).then(stepTwo);
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "step",
+      type: "Step",
+      description: "The step instance that should execute after the previous step completes",
path: docs/src/content/en/reference/vNextWorkflows/then.mdx
user: login: greptile-apps[bot]
body: style: Description should mention that step's inputSchema must match previous step's outputSchema

```suggestion
      description: "The step instance that should execute after the previous step completes. The step's input schema must be compatible with the previous step's output schema.",
```
created_at: 2025-05-16T10:37:45Z
author_association: CONTRIBUTOR

PR comments:
user: login: codesandbox[bot]
created_at: 2025-05-16T10:32:20Z
body: #### Review or Edit in CodeSandbox

Open the branch in <a href="https://codesandbox.io/p/github/mastra-ai/mastra/docs/vnext-api-ref?mode=review&utm_source=gh_app">Web Editor</a> &bull; <a href="https://codesandbox.io/p/vscode?owner=mastra-ai&repo=mastra&branch=docs/vnext-api-ref&utm_source=gh_app">VS Code</a> &bull; <a href="https://codesandbox.io/p/vscode?owner=mastra-ai&repo=mastra&branch=docs/vnext-api-ref&insiders=true&utm_source=gh_app">Insiders</a><br>
Open <a href="https://codesandbox.io/p/devtool/preview/mastra-ai/mastra/docs/vnext-api-ref?task=preview&port=51423&redirect=true&utm_source=gh_app">Preview</a>

<!-- open-in-codesandbox:complete -->

author_association: NONE
user: login: changeset-bot[bot]
created_at: 2025-05-16T10:32:21Z
body: ###  ⚠️  No Changeset found

Latest commit: 6e493899bb00edbd4d209fb26f4259939e6c2d0e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. **If these changes should result in a version bump, you need to add a changeset.**

<details><summary>This PR includes no changesets</summary>

  When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

</details>

[Click here to learn what changesets are, and how to add one](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md).

[Click here if you're a maintainer who wants to add a changeset to this PR](https://github.com/mastra-ai/mastra/new/docs/vnext-api-ref?filename=.changeset/calm-moles-talk.md&value=---%0A%0A---%0A%0AAdd%20vNext%20Workflow%20API%20reference%0A)


author_association: NONE
user: login: vercel[bot]
created_at: 2025-05-16T10:32:22Z
body: [vc]: #Zjw/jaAR4pyql36rReznHkq3xsD0qINZA4HZ+0Iw7Bc=:eyJpc01vbm9yZXBvIjp0cnVlLCJ0eXBlIjoiZ2l0aHViIiwicHJvamVjdHMiOlt7Im5hbWUiOiJtYXN0cmEtZG9jcyIsInJvb3REaXJlY3RvcnkiOiJkb2NzIiwiaW5zcGVjdG9yVXJsIjoiaHR0cHM6Ly92ZXJjZWwuY29tL2tlcGxlci1hYjFiZjVhYi9tYXN0cmEtZG9jcy9FMWR5WThWQW1MRmZRSHJ4R1RTc3ZSNTVUa1FFIiwicHJldmlld1VybCI6Im1hc3RyYS1kb2NzLWdpdC1kb2NzLXZuZXh0LWFwaS1yZWYta2VwbGVyLWFiMWJmNWFiLnZlcmNlbC5hcHAiLCJuZXh0Q29tbWl0U3RhdHVzIjoiREVQTE9ZRUQiLCJsaXZlRmVlZGJhY2siOnsicmVzb2x2ZWQiOjAsInVucmVzb2x2ZWQiOjAsInRvdGFsIjowLCJsaW5rIjoibWFzdHJhLWRvY3MtZ2l0LWRvY3Mtdm5leHQtYXBpLXJlZi1rZXBsZXItYWIxYmY1YWIudmVyY2VsLmFwcCJ9fSx7Im5hbWUiOiJvcGVuYXBpLXNwZWMtd3JpdGVyIiwicm9vdERpcmVjdG9yeSI6ImV4YW1wbGVzL29wZW5hcGktc3BlYy13cml0ZXIiLCJpbnNwZWN0b3JVcmwiOiJodHRwczovL3ZlcmNlbC5jb20va2VwbGVyLWFiMWJmNWFiL29wZW5hcGktc3BlYy13cml0ZXIvNDVBQUp2c21RTUdnTEdSVUw2c3hUSEJ5OFZodCIsInByZXZpZXdVcmwiOiJvcGVuYXBpLXNwZWMtd3JpdGVyLWdpdC1kb2NzLXZuZXh0LWFwaS1yZWYta2VwbGVyLWFiMWJmNWFiLnZlcmNlbC5hcHAiLCJuZXh0Q29tbWl0U3RhdHVzIjoiREVQTE9ZRUQiLCJsaXZlRmVlZGJhY2siOnsicmVzb2x2ZWQiOjAsInVucmVzb2x2ZWQiOjAsInRvdGFsIjowLCJsaW5rIjoib3BlbmFwaS1zcGVjLXdyaXRlci1naXQtZG9jcy12bmV4dC1hcGktcmVmLWtlcGxlci1hYjFiZjVhYi52ZXJjZWwuYXBwIn19LHsibmFtZSI6InRyYXZlbC1haSIsInJvb3REaXJlY3RvcnkiOiJleGFtcGxlcy90cmF2ZWwtYXBwIiwiaW5zcGVjdG9yVXJsIjoiaHR0cHM6Ly92ZXJjZWwuY29tL2tlcGxlci1hYjFiZjVhYi90cmF2ZWwtYWkvRFVXd0Fob1E5cGJkcHNuSGNQRnlBc3FHcHI1eSIsInByZXZpZXdVcmwiOiIiLCJuZXh0Q29tbWl0U3RhdHVzIjoiQ0FOQ0VMRUQiLCJsaXZlRmVlZGJhY2siOnsicmVzb2x2ZWQiOjAsInVucmVzb2x2ZWQiOjAsInRvdGFsIjowLCJsaW5rIjoiIn19LHsibmFtZSI6ImFzc2lzdGFudC11aSIsInJvb3REaXJlY3RvcnkiOiJleGFtcGxlcy9hc3Npc3RhbnQtdWkiLCJpbnNwZWN0b3JVcmwiOiJodHRwczovL3ZlcmNlbC5jb20va2VwbGVyLWFiMWJmNWFiL2Fzc2lzdGFudC11aS84THRXVHM0eE5xUmU5MkpQV1Z0VVhnQXl6MWRIIiwicHJldmlld1VybCI6ImFzc2lzdGFudC11aS1naXQtZG9jcy12bmV4dC1hcGktcmVmLWtlcGxlci1hYjFiZjVhYi52ZXJjZWwuYXBwIiwibmV4dENvbW1pdFN0YXR1cyI6IkRFUExPWUVEIiwibGl2ZUZlZWRiYWNrIjp7InJlc29sdmVkIjowLCJ1bnJlc29sdmVkIjowLCJ0b3RhbCI6MCwibGluayI6ImFzc2lzdGFudC11aS1naXQtZG9jcy12bmV4dC1hcGktcmVmLWtlcGxlci1hYjFiZjVhYi52ZXJjZWwuYXBwIn19XX0=
**The latest updates on your projects**. Learn more about [Vercel for Git ↗︎](https://vercel.link/github-learn-more)

| Name | Status | Preview | Comments | Updated (UTC) |
| :--- | :----- | :------ | :------- | :------ |
| **assistant-ui** | ✅ Ready ([Inspect](https://vercel.com/kepler-ab1bf5ab/assistant-ui/8LtWTs4xNqRe92JPWVtUXgAyz1dH)) | [Visit Preview](https://assistant-ui-git-docs-vnext-api-ref-kepler-ab1bf5ab.vercel.app) | 💬 [**Add feedback**](https://vercel.live/open-feedback/assistant-ui-git-docs-vnext-api-ref-kepler-ab1bf5ab.vercel.app?via=pr-comment-feedback-link) | May 16, 2025 2:44pm |
| **mastra-docs** | ✅ Ready ([Inspect](https://vercel.com/kepler-ab1bf5ab/mastra-docs/E1dyY8VAmLFfQHrxGTSsvR55TkQE)) | [Visit Preview](https://mastra-docs-git-docs-vnext-api-ref-kepler-ab1bf5ab.vercel.app) | 💬 [**Add feedback**](https://vercel.live/open-feedback/mastra-docs-git-docs-vnext-api-ref-kepler-ab1bf5ab.vercel.app?via=pr-comment-feedback-link) | May 16, 2025 2:44pm |
| **openapi-spec-writer** | ✅ Ready ([Inspect](https://vercel.com/kepler-ab1bf5ab/openapi-spec-writer/45AAJvsmQMGgLGRUL6sxTHBy8Vht)) | [Visit Preview](https://openapi-spec-writer-git-docs-vnext-api-ref-kepler-ab1bf5ab.vercel.app) | 💬 [**Add feedback**](https://vercel.live/open-feedback/openapi-spec-writer-git-docs-vnext-api-ref-kepler-ab1bf5ab.vercel.app?via=pr-comment-feedback-link) | May 16, 2025 2:44pm |
| **travel-ai** | 🛑 Canceled ([Inspect](https://vercel.com/kepler-ab1bf5ab/travel-ai/DUWwAhoQ9pbdpsnHcPFyAsqGpr5y)) |  |  | May 16, 2025 2:44pm |





author_association: NONE