@mastra/mcp-docs-server 1.2.19-alpha.0 → 1.2.19-alpha.13

package/.docs/docs/sandbox/overview.md

@@ -2,27 +2,27 @@
 
 # Sandboxes and filesystems
 
-A sandbox gives your agent an environment where it can run commands, execute code, install dependencies, and manage processes. Sandboxes can isolate potentially risky agent-run code from your host, and they can also provide a place to run longer-lived or more resource-intensive work outside your application process.
+A sandbox gives your agent an isolated environment where it can run commands, execute code, install dependencies, and manage processes. This lets agents perform work that would be risky, resource-intensive, or impractical to run directly inside your application.
 
-[Filesystems](https://mastra.ai/docs/sandbox/filesystem) give the agent files it can read, write, and [search](https://mastra.ai/docs/sandbox/search). They can provide a knowledge base for your agent, or be shared with a sandbox so commands can work with the same files and keep data beyond the sandbox's lifetime.
+Sandboxes are often temporary, so files created inside them may disappear when the environment stops. A [filesystem](https://mastra.ai/docs/sandbox/filesystem) gives the agent a place to read, write, and [search](https://mastra.ai/docs/sandbox/search) files that can outlive the sandbox. You can use one to keep outputs between runs, seed a new sandbox with existing files, or give the agent documents it can search while working. Filesystems also work without a sandbox, for example when an agent only needs a knowledge base or access to files in a service such as Google Drive.
 
 ## When to use sandboxes
 
-Sandboxes work well for:
+Use a sandbox when an agent needs to:
 
-- **Coding agents and software factories**: Clone repositories and run shell, Git, build, or test workflows without giving autonomous agents access to the host system.
-- **Deep research and analysis**: Use specialized libraries to process downloaded PDFs or presentations and produce new artifacts.
-- **Long-running and parallel tasks**: Run work in separate environments without tying it to one request or sharing files and processes.
+- Clone repositories and run shell, Git, build, or test workflows in a separate environment.
+- Process PDFs, presentations, or other files with specialized libraries and produce new artifacts.
+- Run long-lived or parallel work in separate environments with isolated files and processes.
 
 If an agent only needs to read, write, or search files, configure [direct filesystem access](https://mastra.ai/docs/sandbox/filesystem).
 
 ## Quickstart
 
-Give an agent a local sandbox and filesystem:
+Give an agent a local sandbox:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
-import { LocalFilesystem, LocalSandbox, Workspace } from '@mastra/core/workspace'
+import { LocalSandbox, Workspace } from '@mastra/core/workspace'
 
 export const codingAgent = new Agent({
   id: 'coding-agent',
@@ -33,20 +33,15 @@ export const codingAgent = new Agent({
     sandbox: new LocalSandbox({
       workingDirectory: './workspace',
     }),
-    filesystem: new LocalFilesystem({
-      basePath: './workspace',
-    }),
   }),
 })
 
 await codingAgent.generate('List the files in the sandbox directory')
 ```
 
-> **Warning:** `LocalSandbox` is the quickest sandbox to set up, but commands run on the host by default. Enable [native isolation](#localsandbox) whenever possible. For applications exposed to untrusted users, use a remote or container backend with a stronger isolation boundary instead.
-
-To use a different sandbox for each user, tenant, or thread, configure a [sandbox resolver](#multi-tenant-sandboxes) instead.
+> **Warning:** `LocalSandbox` runs commands on the application host by default and isn't isolated or secure. Enable [native isolation](#localsandbox), or use a remote or container sandbox when running untrusted code.
 
-The `LocalSandbox` above is one static instance. Every request and memory thread that uses `codingAgent` shares its files, processes, and lifecycle state. A memory thread doesn't create an isolated sandbox by itself.
+A static sandbox is shared across every request and memory thread that uses the agent. Use a [resolver](#sandboxes-per-user-or-thread) when each user or thread needs a separate environment. See [Lifecycle and persistence](#lifecycle-and-persistence) for sharing and cleanup details.
 
 ## Using the sandbox
 
@@ -74,7 +69,7 @@ const workspace = new Workspace({
 })
 ```
 
-Omitting a tool entry keeps its capability-driven default. Set `{ enabled: false }` on one tool to remove it, or set the top-level `enabled: false` to disable generated tools by default. A per-tool `{ enabled: true }` overrides that global setting. The top-level `requireApproval` policy applies to every generated tool unless a per-tool entry overrides it.
+Set `{ enabled: false }` on one tool to remove it, or set the top-level `enabled: false` to disable generated tools by default. A per-tool `{ enabled: true }` overrides that global setting. The top-level `requireApproval` policy applies to every generated tool unless a per-tool entry overrides it.
 
 See the [sandbox tools reference](https://mastra.ai/reference/workspace/workspace-class) for all generated tools and the [tool configuration reference](https://mastra.ai/reference/workspace/workspace-class) for approvals, output limits, and hooks.
 
@@ -109,17 +104,12 @@ export const startServerTool = createTool({
 })
 ```
 
-## Supported backends
+## Sandboxes
 
 ### `LocalSandbox`
 
 [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) executes commands on the same machine as your Mastra application. By default, commands run directly on the host with the permissions of the application process.
 
-Enable native isolation to restrict filesystem and network access at the operating-system level:
-
-- **macOS**: Seatbelt (`sandbox-exec`)
-- **Linux**: Bubblewrap (`bwrap`)
-
 ```typescript
 const sandbox = new LocalSandbox({
   workingDirectory: './workspace',
@@ -131,11 +121,13 @@ const sandbox = new LocalSandbox({
 })
 ```
 
-Use `LocalSandbox.detectIsolation()` to check whether Seatbelt or Bubblewrap is available on the current operating system. The [`nativeSandbox` options](https://mastra.ai/reference/workspace/local-sandbox) control network access, read-only or writable paths, write access to the working directory, and system binaries. You can also provide a custom Seatbelt profile or Bubblewrap arguments. See [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) for the full configuration.
+Enable native isolation to restrict filesystem and network access at the operating-system level. On macOS, native isolation uses Seatbelt (`sandbox-exec`). On Linux, it uses Bubblewrap (`bwrap`). Use `LocalSandbox.detectIsolation()` to check whether Seatbelt or Bubblewrap is available on the current operating system.
 
-### Other backends
+The [`nativeSandbox` options](https://mastra.ai/reference/workspace/local-sandbox) control network access, read-only or writable paths, write access to the working directory, and system binaries. You can also provide a custom Seatbelt profile or Bubblewrap arguments. See [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) for the full configuration.
 
-Use a remote or container backend when commands need a stronger boundary from the host application or when workloads need to scale beyond the resources of your application server. Each backend has its own isolation, persistence, networking, and mount behavior:
+### Remote sandboxes
+
+Use a remote or container sandbox when commands need a stronger boundary from the host application or when workloads need to scale beyond the resources of your application server. Each sandbox has its own isolation, persistence, networking, and mount behavior:
 
 - [AgentCore](https://mastra.ai/integrations/sandboxes/agentcore)
 - [Apple Container](https://mastra.ai/integrations/sandboxes/apple-container)
@@ -149,47 +141,40 @@ Use a remote or container backend when commands need a stronger boundary from th
 - [Railway](https://mastra.ai/integrations/sandboxes/railway)
 - [Vercel](https://mastra.ai/integrations/sandboxes/vercel)
 
-If Mastra doesn't support your execution backend, implement the [sandbox provider interface](https://mastra.ai/reference/workspace/sandbox) to add it.
+If Mastra doesn't support your sandbox provider, implement the [sandbox provider interface](https://mastra.ai/reference/workspace/sandbox) to add it.
 
 ## Filesystem
 
-Each sandbox has a native filesystem that commands can use. Treat it as ephemeral because its contents follow the sandbox's lifecycle.
+Every sandbox has a filesystem for commands. `LocalSandbox` uses the host filesystem, while remote sandboxes have isolated filesystems that are often temporary. For files that need to outlive a sandbox, use external storage.
+
+Mastra filesystems connect agents and sandboxes to provider-backed storage such as Amazon S3, Google Cloud Storage, or Google Drive. Configuring one gives the agent tools to read, write, and search files. When a remote sandbox and provider support mounting, Mastra automatically mounts the storage through Filesystem in Userspace (FUSE). Commands use normal file paths while the provider stores changes outside the sandbox.
 
-To seed a sandbox with files or keep files between runs, give the agent a [filesystem](https://mastra.ai/docs/sandbox/filesystem). Use mounts when sandbox commands need access to the same files.
+See [Filesystem](https://mastra.ai/docs/sandbox/filesystem) for providers, file tools, and mounts.
 
-## Multi-tenant sandboxes
+## Sandboxes per user or thread
 
 Use a **resolver** when each user, tenant, or thread needs a separate sandbox. Set `sandboxCacheKey` to the identity that owns the sandbox so later requests reuse the same live environment.
 
 This example creates and caches one Daytona sandbox per user:
 
 ```typescript
-import type { RequestContext } from '@mastra/core/request-context'
 import { Workspace } from '@mastra/core/workspace'
 import { DaytonaSandbox } from '@mastra/daytona'
 
-const getUserId = (requestContext: RequestContext) => {
-  const userId = requestContext.get('user-id')
-  if (typeof userId !== 'string' || !userId) {
-    throw new Error('A user ID is required to resolve this sandbox')
-  }
-
-  return userId
-}
-
 const workspace = new Workspace({
   sandbox: async ({ requestContext }) => {
-    const sandbox = new DaytonaSandbox({ id: `user-${getUserId(requestContext)}` })
+    const userId = requestContext.get('user-id') as string
+    const sandbox = new DaytonaSandbox({ id: `user-${userId}` })
     await sandbox.start()
     return sandbox
   },
-  sandboxCacheKey: ({ requestContext }) => getUserId(requestContext),
+  sandboxCacheKey: ({ requestContext }) => requestContext.get('user-id') as string,
 })
 ```
 
 The first request from a user creates the sandbox. Later requests with the same user ID reuse it.
 
-For a sandbox with persistent storage, create the filesystem and mount it inside the resolver. This example creates one Daytona sandbox and one S3 storage prefix per memory thread, then mounts the storage at `/workspace`:
+For a sandbox with persistent storage, create a [filesystem](https://mastra.ai/docs/sandbox/filesystem) and mount it inside the resolver. This example creates one Daytona sandbox and one S3 storage prefix per memory thread, then mounts the storage at `/workspace`:
 
 ```typescript
 import { MASTRA_THREAD_ID_KEY, type RequestContext } from '@mastra/core/request-context'
@@ -197,14 +182,8 @@ import { Workspace } from '@mastra/core/workspace'
 import { DaytonaSandbox } from '@mastra/daytona'
 import { S3Filesystem } from '@mastra/s3'
 
-const getThreadId = (requestContext: RequestContext) => {
-  const threadId = requestContext.get(MASTRA_THREAD_ID_KEY)
-  if (typeof threadId !== 'string' || !threadId) {
-    throw new Error('A memory thread is required to resolve this sandbox')
-  }
-
-  return threadId
-}
+const getThreadId = (requestContext: RequestContext) =>
+  requestContext.get(MASTRA_THREAD_ID_KEY) as string
 
 const createThreadFilesystem = (threadId: string) =>
   new S3Filesystem({
@@ -234,25 +213,13 @@ The first request in a thread runs the resolver and starts the sandbox. Later re
 
 The example mounts the filesystem inside the resolver because static `mounts` can't be combined with a sandbox resolver. Generated tools resolve the filesystem and sandbox from the request context automatically.
 
-### Resolver ownership
-
-You are responsible for every sandbox returned by a resolver. It must be ready to use when returned. Keep track of it and destroy it through your application lifecycle code when it's no longer needed. `workspace.destroy()` doesn't destroy resolver-returned sandboxes.
-
-Resolvers are incompatible with `mounts` and [`lsp: true`](https://mastra.ai/docs/sandbox/lsp), because both require a static sandbox during configuration. Using a resolver with `mounts` throws an `INVALID_CONFIG` error. With `lsp: true`, Mastra disables LSP and logs a warning.
+> **Warning:** Your application owns sandboxes returned by a resolver. Destroy them and call `workspace.clearSandboxCache(cacheKey)` when the user, thread, or session ends. `workspace.destroy()` doesn't destroy resolver-returned sandboxes.
 
 ### Tool availability
 
-With a static sandbox, Mastra knows which capabilities the backend supports and only gives the agent the corresponding tools. Application code should also check that an optional capability is available before using it:
-
-```typescript
-const processManager = workspace.sandbox?.processes
-
-if (processManager) {
-  await processManager.spawn('pnpm dev')
-}
-```
+With a static sandbox, Mastra knows which capabilities the backend supports and only gives the agent the corresponding tools. Application code should also check that an optional capability is available before using it.
 
-With a [resolver-backed sandbox](#multi-tenant-sandboxes), the backend isn't known until a request runs, so Mastra initially makes all sandbox tools available. If the resolved backend doesn't support the tool the agent calls, the call fails with `SandboxFeatureNotSupportedError`.
+With a [resolver-backed sandbox](#sandboxes-per-user-or-thread), the backend isn't known until a request runs, so Mastra initially makes all sandbox tools available. If the resolved backend doesn't support the tool the agent calls, the call fails with `SandboxFeatureNotSupportedError`.
 
 ## Background processes
 
@@ -292,7 +259,7 @@ Who shares a sandbox depends on where you configure it and whether you use a res
 | Resource-scoped resolver   | The resolver caches one sandbox for each resource ID.                                                                               |
 | Thread-scoped resolver     | A memory thread keeps its sandbox across requests in that thread.                                                                   |
 
-A static sandbox isn't automatically scoped to the current resource or memory thread. For resource or thread scope, use a resolver and set `sandboxCacheKey` to the corresponding ID. See [Multi-tenant sandboxes](#multi-tenant-sandboxes).
+A static sandbox isn't automatically scoped to the current resource or memory thread. For resource or thread scope, use a resolver and set `sandboxCacheKey` to the corresponding ID. See [Sandboxes per user or thread](#sandboxes-per-user-or-thread).
 
 ### Start
 

package/.docs/docs/server/middleware.md

@@ -6,6 +6,10 @@ Mastra servers can execute custom middleware functions before or after an API ro
 
 A middleware receives the [Hono](https://hono.dev) `Context` (`c`) and a `next` function. If it returns a `Response` the request is short-circuited. Calling `next()` continues processing the next middleware or route handler.
 
+> **Note:** Middleware handlers use Hono's signature, so they run on Hono-based serving paths: `mastra dev` and `mastra build`, the [Hono adapter](https://mastra.ai/reference/server/hono-adapter), and adapters built on it such as `@mastra/next` and `@mastra/tanstack-start`. Adapters for other frameworks (Express, Fastify, Koa) can't run Hono handlers and log a warning at startup when middleware is configured. Register middleware through the framework's own API there instead.
+>
+> User middleware never runs on routes declared public with `requiresAuth: false`, so it can't block endpoints the framework needs to keep reachable, such as the Studio sign-in routes.
+
 ```typescript
 import { Mastra } from '@mastra/core'
 

package/.docs/docs/server/server-adapters.md

@@ -424,11 +424,12 @@ See the [NestJS Adapter](https://mastra.ai/reference/server/nestjs-adapter) docu
 
 ## Initialization flow
 
-Calling `init()` runs three steps in order. Understanding this flow helps when you need to insert your own middleware at specific points.
+Calling `init()` runs four steps in order. Understanding this flow helps when you need to insert your own middleware at specific points.
 
 1. `registerContextMiddleware()`: Attaches the Mastra instance, request context, tools, and abort signal to every request. This makes Mastra available to all subsequent middleware and route handlers.
 2. `registerAuthMiddleware()`: Runs the adapter auth hook during initialization. Official adapters enforce auth inline when Mastra registers built-in routes and `registerApiRoute()` routes, so raw framework routes should use the adapter's exported `createAuthMiddleware()` helper when they need Mastra auth.
-3. `registerRoutes()`: Registers all Mastra API routes for agents, workflows, and other features. Also registers MCP routes if MCP servers are configured.
+3. `registerUserMiddleware()`: Registers [middleware](https://mastra.ai/docs/server/middleware) from the `server.middleware` config and `mastra.setServerMiddleware()`. Middleware handlers use Hono's signature, so Hono-based adapters (`@mastra/hono` and the adapters built on it) mount them; other adapters log a warning instead of silently ignoring the config.
+4. `registerRoutes()`: Registers all Mastra API routes for agents, workflows, and other features. Also registers MCP routes if MCP servers are configured.
 
 ### Manual initialization
 
@@ -445,6 +446,9 @@ server.registerContextMiddleware();
 // Middleware that needs Mastra context
 app.use(customMiddleware);
 
+// Registers `server.middleware` and `setServerMiddleware()` middleware
+server.registerUserMiddleware();
+
 await server.registerRoutes();
 
 // Routes after Mastra
@@ -566,11 +570,12 @@ When using server adapters, configuration comes from two places: the Mastra `ser
 
 The adapter reads these settings from `mastra.getServer()`:
 
-| Option          | Description                                                                                                                                     |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `auth`          | Authentication config, used by `registerAuthMiddleware()`.                                                                                      |
-| `bodySizeLimit` | Default body size limit in bytes. Can be overridden per-adapter via `bodyLimitOptions`.                                                         |
-| `onError`       | Custom error handler called when an unhandled error occurs in a route handler. See [server.onError](https://mastra.ai/reference/configuration). |
+| Option          | Description                                                                                                                                                                                                       |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `auth`          | Authentication config, used by `registerAuthMiddleware()`.                                                                                                                                                        |
+| `bodySizeLimit` | Default body size limit in bytes. Can be overridden per-adapter via `bodyLimitOptions`.                                                                                                                           |
+| `onError`       | Custom error handler called when an unhandled error occurs in a route handler. See [server.onError](https://mastra.ai/reference/configuration).                                                                   |
+| `middleware`    | User [middleware](https://mastra.ai/docs/server/middleware), registered by `registerUserMiddleware()`. Hono-based adapters run it; Express, Fastify, and Koa log a warning because Hono handlers can't run there. |
 
 ### Adapter constructor only
 
@@ -595,7 +600,6 @@ These `server` config options are only used by `mastra build` and have no effect
 | `cors`         | `mastra build` adds CORS middleware     |
 | `timeout`      | `mastra build`                          |
 | `apiRoutes`    | `registerApiRoute()` for `mastra build` |
-| `middleware`   | Middleware config for `mastra build`    |
 
 When using adapters, configure these features directly with your framework. For example, add CORS middleware using Hono's or Express's built-in CORS packages, and set the port when calling your framework's listen function.
 

package/.docs/docs/storage.md

@@ -207,6 +207,7 @@ Each provider page includes installation instructions, configuration parameters,
 - [OracleDB](https://mastra.ai/integrations/databases/oracledb)
 - [PostgreSQL](https://mastra.ai/integrations/databases/postgresql)
 - [Redis](https://mastra.ai/integrations/databases/redis)
+- [Valkey](https://mastra.ai/integrations/databases/valkey)
 - [Upstash](https://mastra.ai/integrations/databases/upstash)
 
 ## Next steps

package/.docs/integrations/databases/mongodb.md

@@ -32,7 +32,7 @@ bun add @mastra/mongodb@latest
 
 ## Usage
 
-Ensure you have a [MongoDB Atlas Local (via Docker)](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-docker/) or [MongoDB Atlas Cloud](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-getting-started/) instance with Atlas Search enabled. MongoDB 7.0+ is recommended.
+Ensure you have a [MongoDB Atlas Local (via Docker)](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-docker/) or [MongoDB Atlas Cloud](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-getting-started/) instance with MongoDB Search enabled. MongoDB 7.0+ is recommended.
 
 ```typescript
 import { MongoDBStore } from '@mastra/mongodb'

package/.docs/integrations/databases/postgresql.md

@@ -146,6 +146,8 @@ PostgreSQL supports observability and can handle low trace volumes. Throughput c
 - Setting up table partitioning for efficient data retention
 - Migrating observability to [ClickHouse via composite storage](https://mastra.ai/reference/storage/composite) if you need to scale further
 
+`PostgresStoreVNext` uses the `event-sourced` [tracing strategy](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage) instead. It writes one row when a span starts and another when it ends, never updating a row in place, and collapses those rows when a trace is read. Writes stay append-only, and traces appear in Studio while the run is still executing.
+
 ### Initialization
 
 When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:

package/.docs/integrations/databases/valkey.md

@@ -0,0 +1,99 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Valkey
+
+The Valkey storage implementation provides persistent storage and server-side caching through the [Valkey GLIDE](https://github.com/valkey-io/valkey-glide) client. Use it when your deployment runs Valkey or needs GLIDE features such as native Valkey configuration and authentication.
+
+Use [`@mastra/redis`](https://mastra.ai/integrations/databases/redis) for Redis deployments that use the official `redis` client. The packages are tested independently against their respective servers.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/valkey
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/valkey
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/valkey
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/valkey
+```
+
+## Usage
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { ValkeyStore } from '@mastra/valkey'
+
+export const mastra = new Mastra({
+  storage: new ValkeyStore({
+    id: 'valkey-storage',
+    host: 'localhost',
+    port: 6379,
+    password: process.env.VALKEY_PASSWORD,
+  }),
+})
+```
+
+You can also provide a native GLIDE configuration:
+
+```typescript
+import { ValkeyStore } from '@mastra/valkey'
+
+const storage = new ValkeyStore({
+  id: 'valkey-storage',
+  config: {
+    addresses: [{ host: 'localhost', port: 6379 }],
+    useTLS: true,
+  },
+})
+```
+
+For an existing `GlideClient`, connect it before passing it to `ValkeyStore`. The caller remains responsible for closing injected clients.
+
+## Constructor parameters
+
+**id** (`string`): Unique identifier for the storage instance.
+
+**host** (`string`): Valkey host address. Use with the direct connection fields.
+
+**port** (`number`): Valkey port. (Default: `6379`)
+
+**username** (`string`): Valkey authentication username. (Default: `default`)
+
+**password** (`string`): Valkey authentication password.
+
+**db** (`number`): Valkey database number. (Default: `0`)
+
+**useTLS** (`boolean`): Enables TLS for direct connections.
+
+**config** (`GlideClientConfiguration`): Native GLIDE standalone client configuration.
+
+**client** (`GlideClient`): Preconfigured GLIDE standalone client.
+
+**disableInit** (`boolean`): Disables automatic storage initialization.
+
+Provide exactly one connection form: `client`, `config`, or `host` with its optional direct connection fields.
+
+## Closing connections
+
+Close clients created by `ValkeyStore` during graceful shutdown:
+
+```typescript
+await storage.close()
+```
+
+`close()` doesn't close an injected `GlideClient`.

package/.docs/integrations/deploy/render.md

@@ -12,7 +12,7 @@ Choose the deployment path that fits your application:
 
 This guide builds an editorial pipeline that reviews a draft from three perspectives in parallel, then passes the feedback to an editor agent. Use the links above if you want to deploy a Mastra API or execute an entire Mastra workflow as one task.
 
-## How Render Workflows works with Mastra
+## How Render Workflows integrate with Mastra
 
 Mastra supplies the agents and application logic, while Render Workflows defines the execution boundaries. A typical pipeline has three layers:
 
@@ -93,8 +93,6 @@ yarn add @renderinc/sdk tsx
 bun add @renderinc/sdk tsx
 ```
 
-> **Note:** Render Workflows requires `@renderinc/sdk@^0.5.0` or later.
-
 Set the API key for your model provider. This example uses OpenAI:
 
 ```text
@@ -103,9 +101,9 @@ OPENAI_API_KEY=your_openai_api_key
 
 Any supported [Mastra model provider](https://mastra.ai/models) works.
 
-## Building a distributed agent pipeline
+## Build a distributed agent pipeline
 
-### Creating the agents
+### Create the agents
 
 In `src/mastra`, create an `agents` directory with `reviewer-agent.ts` and `editor-agent.ts`. Define both agents:
 
@@ -139,7 +137,7 @@ export const editorAgent = new Agent({
 })
 ```
 
-### Configuring the Mastra instance
+### Configure the Mastra instance
 
 Add both agents to the Mastra instance in `src/mastra/index.ts`:
 
@@ -158,7 +156,7 @@ export const mastra = new Mastra({
 
 Retrieving agents from the Mastra instance gives them access to shared application services such as logging, storage, and observability.
 
-### Creating the review task
+### Create the review task
 
 In `src`, create a `tasks` directory. The reviewer agent handles one area of focus. Its compute plan, five-minute timeout, and retry policy apply only to that analysis. A temporary model-provider failure can trigger another attempt without restarting the other reviewers.
 
@@ -199,7 +197,7 @@ export const reviewDraft = task(
 )
 ```
 
-### Creating the revision task
+### Create the revision task
 
 This task combines the feedback and produces a revised draft. It uses a larger compute plan and a longer timeout than each reviewer.
 
@@ -240,7 +238,7 @@ export const reviseDraft = task(
 )
 ```
 
-### Creating the orchestration task
+### Create the orchestration task
 
 The parent dispatches three reviews in parallel with `Promise.all()`, then sends their combined feedback to the revision step. Retries are disabled at this level because each child defines its own policy. If you enable orchestration retries, ensure that another attempt cannot duplicate external side effects or other non-idempotent work.
 
@@ -268,7 +266,7 @@ export const editorialPipeline = task(
 )
 ```
 
-### Registering the tasks
+### Register the tasks
 
 Create `src/index.ts` and import the editorial task:
 
@@ -278,7 +276,7 @@ import './tasks/editorial-task.js'
 
 Running the entry point loads the module and registers every task defined with `task()`.
 
-`create mastra` already wrote `tsconfig.json` and `package.json`. Keep those files. For the workflow start command, `tsc` must emit JavaScript into `dist`, so set these compiler options (do not leave `noEmit: true`):
+Change your `tsconfig.json`:
 
 ```json
 {
@@ -292,7 +290,7 @@ Running the entry point loads the module and registers every task defined with `
 }
 ```
 
-Add these scripts next to the ones `create mastra` already added. `create mastra` already sets `"type": "module"`:
+Add these scripts to `package.json`:
 
 ```json
 {
@@ -304,13 +302,11 @@ Add these scripts next to the ones `create mastra` already added. `create mastra
 }
 ```
 
-Relative imports in the examples above end in `.js` because Node resolves the compiled output as ES modules. Keep those extensions so the built entry point resolves its imports.
-
-Those files are the complete pipeline. [render-examples/render-workflows-mastra](https://github.com/render-examples/render-workflows-mastra) mirrors this `src/` layout and adds a web UI that starts the parent task. Its agents use the provider-specific model ID `openai/gpt-5.6-sol`. In this page's source, that value is represented by a documentation token that is replaced during the docs build. Clone it to skip copying the snippets before you run it.
+Those files are the complete pipeline. [render-examples/render-workflows-mastra](https://github.com/render-examples/render-workflows-mastra) mirrors this `src/` layout and adds a web UI that starts the parent task.
 
-## Running the pipeline
+## Run the pipeline
 
-### Running locally
+### Local
 
 Start the local Render Workflows development server:
 
@@ -334,56 +330,56 @@ render workflows tasks start editorial_pipeline \
 
 The local server keeps runs and their logs in memory, so you can inspect them after they finish with `render workflows runs list <task-name> --local`.
 
-### Running in production
+### Production
 
 Running the pipeline on Render requires a _workflow service_. This is the Render service that holds your task definitions: it builds your repository, registers every task it finds, and provisions an instance for each run.
 
-#### 1. Push the project to a Git repository
+1. #### Push the project to a Git repository
 
-Render builds workflow services from a repository on GitHub, GitLab, or Bitbucket, so push your project to one of those providers. The first time you use a provider, Render asks for permission to access your repositories.
+   Render builds workflow services from a repository on GitHub, GitLab, or Bitbucket, so push your project to one of those providers. The first time you use a provider, Render asks for permission to access your repositories.
 
-#### 2. Create the workflow service
+2. #### Create the workflow service
 
-In the [Render Dashboard](https://dashboard.render.com), click **New > Workflow** and link the repository from the previous step. Then complete the creation form:
+   In the [Render Dashboard](https://dashboard.render.com), click **New > Workflow** and link the repository from the previous step. Then complete the creation form:
 
-| Field             | Value                                                         |
-| ----------------- | ------------------------------------------------------------- |
-| **Language**      | Node                                                          |
-| **Region**        | The region of any other Render services your tasks connect to |
-| **Build Command** | `npm install && npm run build`                                |
-| **Start Command** | `npm run start:workflows`                                     |
+   | Field             | Value                                                         |
+   | ----------------- | ------------------------------------------------------------- |
+   | **Language**      | Node                                                          |
+   | **Region**        | The region of any other Render services your tasks connect to |
+   | **Build Command** | `npm install && npm run build`                                |
+   | **Start Command** | `npm run start:workflows`                                     |
 
-Click **Deploy Workflow**. Render builds the project and registers `review_draft`, `revise_draft`, and `editorial_pipeline`, which then appear on the workflow's **Tasks** page.
+   Click **Deploy Workflow**. Render builds the project and registers `review_draft`, `revise_draft`, and `editorial_pipeline`, which then appear on the workflow's **Tasks** page.
 
-The Render CLI creates the same service without leaving your terminal:
+   The Render CLI creates the same service without leaving your terminal:
 
-```bash
-render workflows create \
-  --name mastra-workflows \
-  --repo . \
-  --runtime node \
-  --build-command "npm install && npm run build" \
-  --run-command "npm run start:workflows"
-```
+   ```bash
+   render workflows create \
+     --name mastra-workflows \
+     --repo . \
+     --runtime node \
+     --build-command "npm install && npm run build" \
+     --run-command "npm run start:workflows"
+   ```
 
-`--repo .` reads the `origin` remote of your local repository, so the project must already be pushed.
+   `--repo .` reads the `origin` remote of your local repository, so the project must already be pushed.
 
-#### 3. Set the workflow's environment variables
+3. #### Set the workflow's environment variables
 
-Add `OPENAI_API_KEY`, or the key for your chosen model provider, to the workflow service in the Dashboard before the first run.
+   Add `OPENAI_API_KEY`, or the key for your chosen model provider, to the workflow service in the Dashboard before the first run.
 
-#### 4. Start a run
+4. #### Start a run
 
-```bash
-render workflows tasks start mastra-workflows/editorial_pipeline \
-  --input='["Render Workflows runs long-running tasks outside the request lifecycle."]'
-```
+   ```bash
+   render workflows tasks start mastra-workflows/editorial_pipeline \
+     --input='["Render Workflows runs long-running tasks outside the request lifecycle."]'
+   ```
 
-The first part of that identifier is your workflow's slug and the second is the task name. Both appear on the task's page in the Render Dashboard, so use the slug shown there if your workflow has a different name.
+   The first part of that identifier is your workflow's slug and the second is the task name. Both appear on the task's page in the Render Dashboard, so use the slug shown there if your workflow has a different name.
 
-Open the workflow in the Render Dashboard to inspect each task run, attempt, result, and log stream.
+   Open the workflow in the Render Dashboard to inspect each task run, attempt, result, and log stream.
 
-## Triggering from your application
+## Trigger from your application
 
 You can trigger the pipeline asynchronously from a Mastra application, web service, or script with the Render SDK.
 
@@ -415,17 +411,6 @@ The task continues running after `startTask()` returns. Call `await run.get()` w
 
 Returning the task run ID from a request handler lets the application respond without keeping the request open for the full pipeline.
 
-## Constraints
-
-These limits live in Render's docs and can change. Prefer those pages over this list:
-
-- Task arguments and return values must be JSON serializable. Arguments to a single run cannot exceed 4 MB. See [defining tasks](https://render.com/docs/workflows-defining#task-arguments) and [Workflows limits](https://render.com/docs/workflows-limits).
-- A task can run for up to 24 hours. The default timeout is two hours. See [timeouts](https://render.com/docs/workflows-defining#timeout).
-- A workflow service can register up to 500 task definitions. See [Workflows limits](https://render.com/docs/workflows-limits).
-- Render Workflows currently supports TypeScript and Python task definitions. See [defining tasks](https://render.com/docs/workflows-defining).
-
-To run the pipeline on a schedule, create a [Render cron job](https://render.com/docs/cronjobs) whose command calls `render workflows tasks start` or `startTask()`.
-
 ## Related
 
 - [Live demo](https://render-workflows-mastra.onrender.com)
@@ -433,4 +418,5 @@ To run the pipeline on a schedule, create a [Render cron job](https://render.com
 - [Defining Render workflow tasks](https://render.com/docs/workflows-defining)
 - [Triggering task runs](https://render.com/docs/workflows-running)
 - [Render Workflows TypeScript SDK](https://render.com/docs/workflows-sdk-typescript)
-- [Render Workflows limits and pricing](https://render.com/docs/workflows-limits)
+- [Render Workflows limits and pricing](https://render.com/docs/workflows-limits)
+- [Render cron jobs](https://render.com/docs/cronjobs)