@mastra/mcp-docs-server 1.0.0-beta.10 → 1.0.0-beta.13

package/.docs/raw/{auth → server/auth}/index.mdx

@@ -11,9 +11,9 @@ You can start with simple shared secret JWT authentication and switch to provide
 
 ## Available providers
 
-- [JSON Web Token (JWT)](/docs/v1/auth/jwt)
-- [Clerk](/docs/v1/auth/clerk)
-- [Supabase](/docs/v1/auth/supabase)
-- [Firebase](/docs/v1/auth/firebase)
-- [WorkOS](/docs/v1/auth/workos)
-- [Auth0](/docs/v1/auth/auth0)
+- [JSON Web Token (JWT)](/docs/v1/server/auth/jwt)
+- [Clerk](/docs/v1/server/auth/clerk)
+- [Supabase](/docs/v1/server/auth/supabase)
+- [Firebase](/docs/v1/server/auth/firebase)
+- [WorkOS](/docs/v1/server/auth/workos)
+- [Auth0](/docs/v1/server/auth/auth0)

package/.docs/raw/{auth → server/auth}/jwt.mdx

@@ -51,7 +51,7 @@ export const mastraClient = new MastraClient({
 });
 ```
 
-> See [Mastra Client SDK](/docs/v1/server-db/mastra-client) for more configuration options.
+> See [Mastra Client SDK](/docs/v1/server/mastra-client) for more configuration options.
 
 ### Making authenticated requests
 

package/.docs/raw/{auth → server/auth}/supabase.mdx

@@ -90,7 +90,7 @@ export const mastraClient = new MastraClient({
 
 > **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
 
-> See [Mastra Client SDK](/docs/v1/server-db/mastra-client) for more configuration options.
+> See [Mastra Client SDK](/docs/v1/server/mastra-client) for more configuration options.
 
 ### Making authenticated requests
 

package/.docs/raw/{auth → server/auth}/workos.mdx

@@ -152,7 +152,7 @@ export const createMastraClient = (accessToken: string) => {
 
 > **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
 
-> See [Mastra Client SDK](/docs/v1/server-db/mastra-client) for more configuration options.
+> See [Mastra Client SDK](/docs/v1/server/mastra-client) for more configuration options.
 
 ### Making authenticated requests
 

package/.docs/raw/{server-db → server}/custom-adapters.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Custom Adapters | Server & DB"
+title: "Custom Adapters | Server"
 description: "Create a custom server adapter for frameworks other than Hono or Express."
 ---
 
@@ -296,7 +296,7 @@ constructor(options: {
 }
 ```
 
-See [Server Adapters](/docs/v1/server-db/server-adapters#constructor-options) for full documentation on each option.
+See [Server Adapters](/docs/v1/server/server-adapters#constructor-options) for full documentation on each option.
 
 ## Full example
 
@@ -379,7 +379,7 @@ The existing [@mastra/hono](https://github.com/mastra-ai/mastra/blob/main/server
 
 ## Related
 
-- [Server Adapters](/docs/v1/server-db/server-adapters) - Overview and shared concepts
+- [Server Adapters](/docs/v1/server/server-adapters) - Overview and shared concepts
 - [Hono Adapter](/reference/v1/server/hono-adapter) - Reference implementation
 - [Express Adapter](/reference/v1/server/express-adapter) - Reference implementation
 - [MastraServer Reference](/reference/v1/server/mastra-server) - Full API reference

package/.docs/raw/{server-db → server}/custom-api-routes.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Custom API Routes | Server & DB"
+title: "Custom API Routes | Server"
 description: "Expose additional HTTP endpoints from your Mastra server."
 ---
 

package/.docs/raw/{server-db → server}/mastra-client.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Mastra Client SDK | Server & DB"
+title: "Mastra Client SDK | Server"
 description: "Learn how to set up and use the Mastra Client SDK"
 ---
 
@@ -8,7 +8,7 @@ import TabItem from "@theme/TabItem";
 
 # Mastra Client SDK
 
-The Mastra Client SDK provides a simple and type-safe interface for interacting with your [Mastra Server](/docs/v1/server-db/mastra-server) from your client environment.
+The Mastra Client SDK provides a simple and type-safe interface for interacting with your [Mastra Server](/docs/v1/server/mastra-server) from your client environment.
 
 ## Prerequisites
 

package/.docs/raw/{server-db → server}/mastra-server.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Server Configuration | Server & DB"
+title: "Server Configuration | Server"
 description: "Configure the Mastra server with custom settings for port, timeout, CORS, and more."
 ---
 
@@ -9,7 +9,7 @@ When deploying your Mastra application to production, it runs as an HTTP server
 
 :::info
 
-This page covers the `server` configuration options passed to the `Mastra` constructor. For running Mastra with your own HTTP server (Hono, Express, etc.), see [Server Adapters](/docs/v1/server-db/server-adapters).
+This page covers the `server` configuration options passed to the `Mastra` constructor. For running Mastra with your own HTTP server (Hono, Express, etc.), see [Server Adapters](/docs/v1/server/server-adapters).
 
 :::
 
@@ -27,26 +27,29 @@ The server provides:
 - Configuration of port
 - Configuration of body limit
 
-See the [Middleware](/docs/v1/server-db/middleware) and
-[Custom API Routes](/docs/v1/server-db/custom-api-routes) pages for details on
+See the [Middleware](/docs/v1/server/middleware) and
+[Custom API Routes](/docs/v1/server/custom-api-routes) pages for details on
 adding additional server behaviour.
 
 ## Server configuration
 
-You can configure server `port` and `timeout` in the Mastra instance.
+You can configure server `port`, `host`, `studioBase`, and `timeout` in the Mastra instance.
 
-```typescript title="src/mastra/index.ts" copy showLineNumbers
+```typescript title="src/mastra/index.ts" copy
 import { Mastra } from "@mastra/core";
 
 export const mastra = new Mastra({
-  // ...
   server: {
     port: 3000, // Defaults to 4111
+    host: "0.0.0.0", // Defaults to 'localhost'
+    studioBase: "/my-mastra-studio", // Sub-path for the studio (optional)
     timeout: 10000, // Defaults to 3 * 60 * 1000 (3 minutes)
   },
 });
 ```
 
+The `studioBase` option allows you to host Mastra Studio on a sub-path of your existing application. For example, with `studioBase: "/my-mastra-studio"`, the studio will be available at `http://your-host:port/my-mastra-studio` instead of the root.
+
 ## TypeScript configuration
 
 Mastra requires `module` and `moduleResolution` values that support modern Node.js versions. Older settings like `CommonJS` or `node` are incompatible with Mastra’s packages and will cause resolution errors.
@@ -74,11 +77,10 @@ Mastra requires `module` and `moduleResolution` values that support modern Node.
 
 Mastra allows you to configure CORS (Cross-Origin Resource Sharing) settings for your server.
 
-```typescript title="src/mastra/index.ts" copy showLineNumbers
+```typescript title="src/mastra/index.ts" copy
 import { Mastra } from "@mastra/core";
 
 export const mastra = new Mastra({
-  // ...
   server: {
     cors: {
       origin: ["https://example.com"], // Allow specific origins or '*' for all
@@ -94,4 +96,4 @@ export const mastra = new Mastra({
 
 When streaming agent responses, the HTTP streaming layer redacts system prompts, tool definitions, API keys, and similar data from each chunk before sending it to clients. This is enabled by default.
 
-If you're using server adapters directly, you can configure redaction behavior. See [Stream data redaction](/docs/v1/server-db/server-adapters#stream-data-redaction) in the Server Adapters docs.
+If you're using server adapters directly, you can configure redaction behavior. See [Stream data redaction](/docs/v1/server/server-adapters#stream-data-redaction) in the Server Adapters docs.

package/.docs/raw/{server-db → server}/middleware.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Middleware | Server & DB"
+title: "Middleware | Server"
 description: "Apply custom middleware functions to intercept requests."
 ---
 
@@ -174,4 +174,4 @@ be inspected by middleware to tailor behavior:
 
 # Related
 
-- [Request Context](/docs/v1/server-db/request-context)
+- [Request Context](/docs/v1/server/request-context)

package/.docs/raw/{server-db → server}/request-context.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Request Context | Server & DB"
+title: "Request Context | Server"
 description: Learn how to use Mastra's RequestContext to provide dynamic, request-specific configuration to agents.
 ---
 
@@ -99,7 +99,7 @@ export const mastra = new Mastra({
 });
 ```
 
-> See [Middleware](/docs/v1/server-db/middleware) for how to use server middleware.
+> See [Middleware](/docs/v1/server/middleware) for how to use server middleware.
 
 ## Accessing values with agents
 
@@ -190,4 +190,4 @@ export const weatherTool = createTool({
 - [Agent Request Context](/docs/v1/agents/overview#using-requestcontext)
 - [Workflow Request Context](../workflows/overview#using-requestcontext)
 - [Tool Request Context](../mcp/overview#using-requestcontext)
-- [Server Middleware](/docs/v1/server-db/middleware)
+- [Server Middleware](/docs/v1/server/middleware)

package/.docs/raw/{server-db → server}/server-adapters.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Server Adapters | Server & DB"
+title: "Server Adapters | Server"
 description: "Manually configure a Mastra server using Hono or Express adapters."
 ---
 
@@ -18,7 +18,7 @@ Server adapters let you run Mastra with your own HTTP server instead of the Hono
 
 :::tip
 
-For simple deployments without custom server requirements, use `mastra build` instead. It configures server setup, registers middleware, and applies deployment settings based on your project configuration. See [Server Configuration](/docs/v1/server-db/mastra-server).
+For deployments without custom server requirements, use `mastra build` instead. It configures server setup, registers middleware, and applies deployment settings based on your project configuration. See [Server Configuration](/docs/v1/server/mastra-server).
 
 :::
 
@@ -29,7 +29,7 @@ Mastra currently provides two official server adapters:
 - [@mastra/express](/reference/v1/server/express-adapter): Express framework adapter
 - [@mastra/hono](/reference/v1/server/hono-adapter): Hono framework adapter
 
-You can build your own adapter, read [Custom Adapters](/docs/v1/server-db/custom-adapters) for details.
+You can build your own adapter, read [Custom Adapters](/docs/v1/server/custom-adapters) for details.
 
 ## Installation
 
@@ -305,8 +305,8 @@ See [MCP](/docs/v1/mcp/overview) for configuration details and how to set up MCP
 
 - [Hono Adapter](/reference/v1/server/hono-adapter) - Hono-specific setup
 - [Express Adapter](/reference/v1/server/express-adapter) - Express-specific setup
-- [Custom Adapters](/docs/v1/server-db/custom-adapters) - Building adapters for other frameworks
-- [Server Configuration](/docs/v1/server-db/mastra-server) - Using `mastra build` instead
-- [Authentication](/docs/v1/auth) - Configuring auth for your server
+- [Custom Adapters](/docs/v1/server/custom-adapters) - Building adapters for other frameworks
+- [Server Configuration](/docs/v1/server/mastra-server) - Using `mastra build` instead
+- [Authentication](/docs/v1/server/auth) - Configuring auth for your server
 - [MastraServer Reference](/reference/v1/server/mastra-server) - Full API reference
 - [createRoute() Reference](/reference/v1/server/create-route) - Creating type-safe custom routes

package/.docs/raw/tools-mcp/overview.mdx

@@ -56,7 +56,7 @@ To make tools available to an agent, you configure them in the agent's definitio
 
 ## Using `RequestContext`
 
-Use [RequestContext](/docs/v1/server-db/request-context) to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
+Use [RequestContext](/docs/v1/server/request-context) to access request-specific values. This lets you conditionally adjust behavior based on the context of the request.
 
 ```typescript title="src/mastra/tools/test-tool.ts" showLineNumbers
 export type UserTier = {
@@ -81,7 +81,7 @@ export const testTool = createTool({
 });
 ```
 
-> See [Request Context](/docs/v1/server-db/request-context) for more information.
+> See [Request Context](/docs/v1/server/request-context) for more information.
 
 ## Testing with Studio
 

package/.docs/raw/workflows/control-flow.mdx

@@ -59,7 +59,7 @@ export const testWorkflow = createWorkflow({
 
 ## Simultaneous steps with `.parallel()`
 
-Use `.parallel()` to run steps at the same time. Each step's `id` is used when defining a following step's `inputSchema` and becomes the key on the `inputData` object used to access the previous step's values. The outputs of parallel steps can then be referenced or combined by a following step.
+Use `.parallel()` to run steps at the same time. All parallel steps must complete before the workflow continues to the next step. Each step's `id` is used when defining a following step's `inputSchema` and becomes the key on the `inputData` object used to access the previous step's values. The outputs of parallel steps can then be referenced or combined by a following step.
 
 ![Concurrent steps with .parallel()](/img/workflows/workflows-control-flow-parallel.jpg)
 
@@ -176,6 +176,8 @@ export const testWorkflow = createWorkflow({
 - The next step receives an object containing all parallel step outputs
 - You must define the `inputSchema` of the following step to match this structure
 
+> See [Choosing the right pattern](#choosing-the-right-pattern) to understand when to use `.parallel()` vs `.foreach()`.
+
 ## Conditional logic with `.branch()`
 
 Use `.branch()` to choose which step to run based on a condition. All steps in a branch need the same `inputSchema` and `outputSchema` because branching requires consistent schemas so workflows can follow different paths.
@@ -428,7 +430,7 @@ export const testWorkflow = createWorkflow({
 
 ### Looping with `.foreach()`
 
-Use `.foreach()` to run the same step for each item in an array. The input must be of type `array` so the loop can iterate over its values, applying the step’s logic to each one.
+Use `.foreach()` to run the same step for each item in an array. The input must be of type `array` so the loop can iterate over its values, applying the step's logic to each one. See [Choosing the right pattern](#choosing-the-right-pattern) for guidance on when to use `.foreach()` vs other methods.
 
 ![Repeating with .foreach()](/img/workflows/workflows-control-flow-foreach.jpg)
 
@@ -454,6 +456,32 @@ export const testWorkflow = createWorkflow({
   .commit();
 ```
 
+#### Output structure
+
+The `.foreach()` method always returns an array containing the output of each iteration. The order of outputs matches the order of inputs.
+
+```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+const addTenStep = createStep({
+  id: "add-ten",
+  inputSchema: z.object({ value: z.number() }),
+  outputSchema: z.object({ value: z.number() }),
+  execute: async ({ inputData }) => ({
+    value: inputData.value + 10
+  })
+});
+
+export const testWorkflow = createWorkflow({
+  id: "foreach-output-example",
+  inputSchema: z.array(z.object({ value: z.number() })),
+  outputSchema: z.array(z.object({ value: z.number() }))
+})
+  .foreach(addTenStep)
+  .commit();
+
+// When executed with [{ value: 1 }, { value: 22 }, { value: 333 }]
+// Output: [{ value: 11 }, { value: 32 }, { value: 343 }]
+```
+
 #### Concurrency limits
 
 Use `concurrency` to control the number of array items processed at the same time. The default is `1`, which runs steps sequentially. Increasing the value allows `.foreach()` to process multiple items simultaneously.
@@ -466,6 +494,324 @@ export const testWorkflow = createWorkflow({...})
   .commit();
 ```
 
+#### Aggregating results after `.foreach()`
+
+Since `.foreach()` outputs an array, you can use `.then()` or `.map()` to aggregate or transform the results. The step following `.foreach()` receives the entire array as its input.
+
+```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+const processItemStep = createStep({
+  id: "process-item",
+  inputSchema: z.object({ value: z.number() }),
+  outputSchema: z.object({ processed: z.number() }),
+  execute: async ({ inputData }) => ({
+    processed: inputData.value * 2
+  })
+});
+
+const aggregateStep = createStep({
+  id: "aggregate",
+  // Input is an array of outputs from foreach
+  inputSchema: z.array(z.object({ processed: z.number() })),
+  outputSchema: z.object({ total: z.number() }),
+  execute: async ({ inputData }) => ({
+    // Sum all processed values
+    total: inputData.reduce((sum, item) => sum + item.processed, 0)
+  })
+});
+
+export const testWorkflow = createWorkflow({
+  id: "foreach-aggregate-example",
+  inputSchema: z.array(z.object({ value: z.number() })),
+  outputSchema: z.object({ total: z.number() })
+})
+  .foreach(processItemStep)
+  .then(aggregateStep)  // Receives the full array from foreach
+  .commit();
+
+// When executed with [{ value: 1 }, { value: 2 }, { value: 3 }]
+// After foreach: [{ processed: 2 }, { processed: 4 }, { processed: 6 }]
+// After aggregate: { total: 12 }
+```
+
+You can also use `.map()` to transform the array output:
+
+```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+export const testWorkflow = createWorkflow({...})
+  .foreach(processItemStep)
+  .map(async ({ inputData }) => ({
+    // Transform the array into a different structure
+    values: inputData.map(item => item.processed),
+    count: inputData.length
+  }))
+  .then(nextStep)
+  .commit();
+```
+
+#### Chaining multiple `.foreach()` calls
+
+When you chain `.foreach()` calls, each operates on the array output of the previous step. This is useful when each item in your array needs to be transformed by multiple steps in sequence.
+
+```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+const chunkStep = createStep({
+  id: "chunk",
+  // Takes a document, returns an array of chunks
+  inputSchema: z.object({ content: z.string() }),
+  outputSchema: z.array(z.object({ chunk: z.string() })),
+  execute: async ({ inputData }) => {
+    // Split document into chunks
+    const chunks = inputData.content.match(/.{1,100}/g) || [];
+    return chunks.map(chunk => ({ chunk }));
+  }
+});
+
+const embedStep = createStep({
+  id: "embed",
+  // Takes a single chunk, returns embedding
+  inputSchema: z.object({ chunk: z.string() }),
+  outputSchema: z.object({ embedding: z.array(z.number()) }),
+  execute: async ({ inputData }) => ({
+    embedding: [/* vector embedding */]
+  })
+});
+
+// For a single document that produces multiple chunks:
+export const singleDocWorkflow = createWorkflow({
+  id: "single-doc-rag",
+  inputSchema: z.object({ content: z.string() }),
+  outputSchema: z.array(z.object({ embedding: z.array(z.number()) }))
+})
+  .then(chunkStep)      // Returns array of chunks
+  .foreach(embedStep)   // Process each chunk -> array of embeddings
+  .commit();
+```
+
+For processing multiple documents where each produces multiple chunks, you have options:
+
+**Option 1: Process all documents in a single step with batching control**
+
+```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+const downloadAndChunkStep = createStep({
+  id: "download-and-chunk",
+  inputSchema: z.array(z.string()),  // Array of URLs
+  outputSchema: z.array(z.object({ chunk: z.string(), source: z.string() })),
+  execute: async ({ inputData: urls }) => {
+    // Control batching/parallelization within the step
+    const allChunks = [];
+    for (const url of urls) {
+      const content = await fetch(url).then(r => r.text());
+      const chunks = content.match(/.{1,100}/g) || [];
+      allChunks.push(...chunks.map(chunk => ({ chunk, source: url })));
+    }
+    return allChunks;
+  }
+});
+
+export const multiDocWorkflow = createWorkflow({...})
+  .then(downloadAndChunkStep)  // Returns flat array of all chunks
+  .foreach(embedStep, { concurrency: 10 })  // Embed each chunk in parallel
+  .commit();
+```
+
+**Option 2: Use foreach for documents, aggregate chunks, then foreach for embeddings**
+
+```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+const downloadStep = createStep({
+  id: "download",
+  inputSchema: z.string(),  // Single URL
+  outputSchema: z.object({ content: z.string(), source: z.string() }),
+  execute: async ({ inputData: url }) => ({
+    content: await fetch(url).then(r => r.text()),
+    source: url
+  })
+});
+
+const chunkDocStep = createStep({
+  id: "chunk-doc",
+  inputSchema: z.object({ content: z.string(), source: z.string() }),
+  outputSchema: z.array(z.object({ chunk: z.string(), source: z.string() })),
+  execute: async ({ inputData }) => {
+    const chunks = inputData.content.match(/.{1,100}/g) || [];
+    return chunks.map(chunk => ({ chunk, source: inputData.source }));
+  }
+});
+
+export const multiDocWorkflow = createWorkflow({
+  id: "multi-doc-rag",
+  inputSchema: z.array(z.string()),  // Array of URLs
+  outputSchema: z.array(z.object({ embedding: z.array(z.number()) }))
+})
+  .foreach(downloadStep, { concurrency: 5 })  // Download docs in parallel
+  .foreach(chunkDocStep)  // Chunk each doc -> array of chunk arrays
+  .map(async ({ inputData }) => {
+    // Flatten nested arrays: [[chunks], [chunks]] -> [chunks]
+    return inputData.flat();
+  })
+  .foreach(embedStep, { concurrency: 10 })  // Embed all chunks
+  .commit();
+```
+
+**Key points about chaining `.foreach()`:**
+- Each `.foreach()` operates on the array from the previous step
+- If a step inside `.foreach()` returns an array, the output becomes an array of arrays
+- Use `.map()` with `.flat()` to flatten nested arrays when needed
+- For complex RAG pipelines, Option 1 (handling batching in a single step) often provides better control
+
+#### Nested workflows inside foreach
+
+The step after `.foreach()` only executes after all iterations complete. If you need to run multiple sequential operations per item, use a nested workflow instead of chaining multiple `.foreach()` calls. This keeps all operations for each item together and makes the data flow clearer.
+
+```typescript title="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+// Define a workflow that processes a single document
+const processDocumentWorkflow = createWorkflow({
+  id: "process-document",
+  inputSchema: z.object({ url: z.string() }),
+  outputSchema: z.object({
+    embeddings: z.array(z.array(z.number())),
+    metadata: z.object({ url: z.string(), chunkCount: z.number() })
+  })
+})
+  .then(downloadStep)      // Download the document
+  .then(chunkStep)         // Split into chunks
+  .then(embedChunksStep)   // Embed all chunks for this document
+  .then(formatResultStep)  // Format the final output
+  .commit();
+
+// Use the nested workflow inside foreach
+export const batchProcessWorkflow = createWorkflow({
+  id: "batch-process-documents",
+  inputSchema: z.array(z.object({ url: z.string() })),
+  outputSchema: z.array(z.object({
+    embeddings: z.array(z.array(z.number())),
+    metadata: z.object({ url: z.string(), chunkCount: z.number() })
+  }))
+})
+  .foreach(processDocumentWorkflow, { concurrency: 3 })
+  .commit();
+
+// Each document goes through all 4 steps before the next document starts (with concurrency: 1)
+// With concurrency: 3, up to 3 documents process their full pipelines in parallel
+```
+
+**Why use nested workflows:**
+- **Better parallelism**: With `concurrency: N`, multiple items run their full pipelines simultaneously. Chained `.foreach().foreach()` processes all items through step 1, waits, then all through step 2 - nested workflows let each item progress independently
+- All steps for one item complete together before results are collected
+- Cleaner than multiple `.foreach()` calls which create nested arrays
+- Each nested workflow execution is independent with its own data flow
+- Easier to test and reuse the per-item logic separately
+
+**How it works:**
+1. The parent workflow passes each array item to an instance of the nested workflow
+2. Each nested workflow runs its full step sequence for that item
+3. With `concurrency > 1`, multiple nested workflows execute in parallel
+4. The nested workflow's final output becomes one element in the result array
+5. After all nested workflows complete, the next step in the parent receives the full array
+
+## Choosing the right pattern
+
+Use this section as a reference for selecting the appropriate control flow method.
+
+### Quick reference
+
+| Method | Purpose | Input | Output | Concurrency |
+|--------|---------|-------|--------|-------------|
+| `.then(step)` | Sequential processing | `T` | `U` | N/A (one at a time) |
+| `.parallel([a, b])` | Different operations on same input | `T` | `{ a: U, b: V }` | All run simultaneously |
+| `.foreach(step)` | Same operation on each array item | `T[]` | `U[]` | Configurable (default: 1) |
+| `.branch([...])` | Conditional path selection | `T` | `{ selectedStep: U }` | Only one branch runs |
+
+### `.parallel()` vs `.foreach()`
+
+**Use `.parallel()` when you have one input that needs different processing:**
+
+```typescript
+// Same user data processed differently in parallel
+workflow
+  .parallel([validateStep, enrichStep, scoreStep])
+  .then(combineResultsStep)
+```
+
+**Use `.foreach()` when you have many inputs that need the same processing:**
+
+```typescript
+// Multiple URLs each processed the same way
+workflow
+  .foreach(downloadStep, { concurrency: 5 })
+  .then(aggregateStep)
+```
+
+### When to use nested workflows
+
+**Inside `.foreach()`** - when each array item needs multiple sequential steps:
+
+```typescript
+// Each document goes through a full pipeline
+const processDocWorkflow = createWorkflow({...})
+  .then(downloadStep)
+  .then(parseStep)
+  .then(embedStep)
+  .commit();
+
+workflow.foreach(processDocWorkflow, { concurrency: 3 })
+```
+
+This is cleaner than chaining `.foreach().foreach()`, which creates nested arrays.
+
+**Inside `.parallel()`** - when a parallel branch needs its own multi-step pipeline:
+
+```typescript
+const pipelineA = createWorkflow({...}).then(step1).then(step2).commit();
+const pipelineB = createWorkflow({...}).then(step3).then(step4).commit();
+
+workflow.parallel([pipelineA, pipelineB])
+```
+
+### Chaining patterns
+
+| Pattern | What happens | Common use case |
+|---------|--------------|-----------------|
+| `.then().then()` | Sequential steps | Simple pipelines |
+| `.parallel().then()` | Run in parallel, then combine | Fan-out/fan-in |
+| `.foreach().then()` | Process all items, then aggregate | Map-reduce |
+| `.foreach().foreach()` | Creates array of arrays | Avoid - use nested workflow or `.map()` with `.flat()` |
+| `.foreach(workflow)` | Full pipeline per item | Multi-step processing per array item |
+
+### Synchronization: when does the next step run?
+
+Both `.parallel()` and `.foreach()` are synchronization points. The next step in the workflow only executes after all parallel branches or all array iterations have completed.
+
+```typescript
+workflow
+  .parallel([stepA, stepB, stepC])  // All 3 run simultaneously
+  .then(combineStep)                // Waits for ALL 3 to finish before running
+  .commit();
+
+workflow
+  .foreach(processStep, { concurrency: 5 })  // Up to 5 items process at once
+  .then(aggregateStep)                       // Waits for ALL items to finish before running
+  .commit();
+```
+
+This means:
+- `.parallel()` collects all branch outputs into an object, then passes it to the next step
+- `.foreach()` collects all iteration outputs into an array, then passes it to the next step
+- There is no way to "stream" results to the next step as they complete
+
+### Concurrency behavior
+
+| Method | Behavior |
+|--------|----------|
+| `.then()` | Sequential - one step at a time |
+| `.parallel()` | All branches run simultaneously (no limit option) |
+| `.foreach()` | Controlled via `{ concurrency: N }` - default is 1 (sequential) |
+| Nested workflow in `.foreach()` | Respects parent's concurrency setting |
+
+**Performance tip:** For I/O-bound operations in `.foreach()`, increase concurrency to process items in parallel:
+
+```typescript
+// Process up to 10 items simultaneously
+workflow.foreach(fetchDataStep, { concurrency: 10 })
+```
+
 ## Loop management
 
 Loop conditions can be implemented in different ways depending on how you want the loop to end. Common patterns include checking values returned in `inputData`, setting a maximum number of iterations, or aborting execution when a limit is reached.