@mastra/mcp-docs-server 1.1.18-alpha.1 → 1.1.18

package/.docs/docs/studio/auth.md

@@ -0,0 +1,142 @@
+# Studio auth
+
+When you configure [authentication](https://mastra.ai/docs/server/auth) on your Mastra server, Studio automatically displays a login screen and enforces access control. One configuration secures both the Studio UI and your API routes.
+
+Without authentication, Studio and all API routes are publicly accessible.
+
+## When to use Studio Auth
+
+- Multiple team members need to interact with agents, workflows, and tools through a shared Studio deployment.
+- Permissions must restrict who can execute agents, edit workflows, or delete datasets.
+- A login screen (SSO, email/password, or both) should gate access to your Studio deployment.
+
+## Quickstart
+
+Add an auth provider to your Mastra server configuration. This example uses [Simple Auth](https://mastra.ai/docs/server/auth/simple-auth) for a minimal setup:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { SimpleAuth } from '@mastra/core/server'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new SimpleAuth({
+      users: {
+        'my-api-key': {
+          id: 'user-1',
+          name: 'Alice',
+          role: 'admin',
+        },
+      },
+    }),
+  },
+})
+```
+
+Once configured, Studio shows a login screen and requires authentication for all API requests.
+
+> **Note:** Visit the [Auth docs](https://mastra.ai/docs/server/auth) for a full list of supported providers.
+
+## How it works
+
+Setting [`server.auth`](https://mastra.ai/reference/configuration) does two things at once:
+
+- **Studio UI**: Displays a login screen. Depending on the provider, users sign in through SSO, email/password, or both.
+- **API routes**: Requires authentication for all built-in routes (`/api/agents/*`, `/api/workflows/*`, etc.) and custom routes. This applies whether requests come from Studio or direct API calls.
+
+Studio detects available capabilities by calling the `GET /api/auth/capabilities` endpoint. The response tells Studio which login methods to render and, if the user is already authenticated, includes their user info and permissions.
+
+## Role-based access control
+
+RBAC lets you control what each user can see and do inside Studio. It's separate from authentication: `server.auth` handles who the user is, while `server.rbac` handles what they can do.
+
+### Default roles
+
+Mastra ships four default roles. Import them from `@mastra/core/auth/ee`:
+
+| Role     | Permissions              |
+| -------- | ------------------------ |
+| `owner`  | Full access (`*`)        |
+| `admin`  | Read, write, and execute |
+| `member` | Read and execute         |
+| `viewer` | Read-only                |
+
+### Enable RBAC
+
+Use `StaticRBACProvider` with the default roles or define your own:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { SimpleAuth } from '@mastra/core/server'
+import { StaticRBACProvider, DEFAULT_ROLES } from '@mastra/core/auth/ee'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new SimpleAuth({
+      users: {
+        'admin-key': { id: 'user-1', name: 'Alice', role: 'admin' },
+        'viewer-key': { id: 'user-2', name: 'Bob', role: 'viewer' },
+      },
+    }),
+    rbac: new StaticRBACProvider({
+      roles: DEFAULT_ROLES,
+      getUserRoles: user => [user.role],
+    }),
+  },
+})
+```
+
+When RBAC is active, Studio hides actions the user doesn't have permission for. A viewer doesn't see delete buttons; a member can't modify agent configurations.
+
+### Permission format
+
+Permissions follow the pattern `{resource}:{action}`, with optional resource-level scoping:
+
+| Pattern             | Meaning                     |
+| ------------------- | --------------------------- |
+| `*`                 | Full access to everything   |
+| `*:read`            | Read all resources          |
+| `agents:*`          | All actions on agents       |
+| `agents:execute`    | Execute agents only         |
+| `agents:read:my-id` | Read a specific agent by ID |
+
+Resources include `agents`, `workflows`, `tools`, `datasets`, `memory`, `scores`, `observability`, and others. Actions are `read`, `write`, `execute`, and `delete`.
+
+### Map external provider roles
+
+If your identity provider already defines roles (for example, Clerk organizations or WorkOS groups), map them to Mastra permissions with `roleMapping`:
+
+```typescript
+import { StaticRBACProvider } from '@mastra/core/auth/ee'
+
+const rbac = new StaticRBACProvider({
+  roleMapping: {
+    'org:admin': ['*'],
+    'org:member': ['*:read', '*:execute'],
+    'org:viewer': ['*:read'],
+  },
+  getUserRoles: user => user.providerRoles,
+})
+```
+
+## Login methods
+
+Studio adapts its login screen based on the auth provider:
+
+| Provider type    | Login UI                                |
+| ---------------- | --------------------------------------- |
+| SSO only         | SSO button (e.g. "Sign in with WorkOS") |
+| Credentials only | Email and password form                 |
+| Both             | SSO button and email/password form      |
+
+Sign-up can be enabled or disabled per provider. When disabled, Studio hides the sign-up link and forces the sign-in form.
+
+## EE licensing
+
+Studio Auth features (SSO login, RBAC, permission-based UI) are part of the Mastra Enterprise Edition. They work without a license during local development and with Simple Auth. For production deployments with third-party providers, a valid EE license is required. [Contact sales](https://mastra.ai/contact) for more information.
+
+## Related
+
+- [Auth overview](https://mastra.ai/docs/server/auth): Full list of supported auth providers.
+- [Studio deployment](https://mastra.ai/docs/studio/deployment): Deploy Studio to production.
+- [Custom API routes](https://mastra.ai/docs/server/custom-api-routes): Control authentication on individual endpoints.

package/.docs/docs/{deployment/studio.md → studio/deployment.md}

@@ -1,15 +1,15 @@
-# Deploying Studio
+# Studio deployment
 
-[Studio](https://mastra.ai/docs/getting-started/studio) provides an interactive UI for building and testing your agents. It's a React-based Single Page Application (SPA) that runs in the browser and connects to a running [Mastra server](https://mastra.ai/docs/deployment/mastra-server).
+Studio is a React-based Single Page Application (SPA) that runs in the browser and connects to a running [Mastra server](https://mastra.ai/docs/deployment/mastra-server).
 
 You can deploy Studio in two primary ways:
 
-- [Mastra Cloud](https://mastra.ai/docs/mastra-cloud/overview) hosts Studio for you and allows you to share access with your team via link
+- [Cloud](https://mastra.ai/docs/mastra-cloud/overview) hosts Studio for you and allows you to share access with your team via link
 - You can self-host Studio on your own infrastructure, either alongside your Mastra server or separately as a standalone SPA
 
 On this page you'll learn how to deploy Studio on your own infrastructure. As the finer details of deployment can vary widely based on your needs and setup, we'll cover the general principles and options available to you.
 
-## Fundamentals
+## Quickstart
 
 The easiest way to run Studio is the [`mastra studio`](https://mastra.ai/reference/cli/mastra) command.
 
@@ -65,7 +65,7 @@ Running `mastra studio` as a long-running process is no different from running a
 
 > **Warning:** Once Studio is connected to your Mastra server, it has full access to your agents, workflows, and tools. Be sure to secure it properly in production (e.g. behind authentication, VPN, etc.) to prevent unauthorized access.
 >
-> Visit the [Authentication](https://mastra.ai/docs/server/auth) docs to learn more.
+> Visit the [Authentication](https://mastra.ai/docs/studio/auth) docs to learn more.
 
 ### Alongside your API
 
@@ -85,7 +85,15 @@ MASTRA_STUDIO_PATH=.mastra/output/studio node .mastra/output/index.mjs
 
 ## Using a CDN
 
-Currently, you can't directly deploy the built Studio assets to a CDN, as the UI relies on some dynamic configuration. With a bit of extra setup, you can create a standalone SPA out of the built assets and deploy it to any static hosting service like Netlify, Vercel, etc.
+### Automatic
+
+Some of the [Cloud providers](https://mastra.ai/docs/deployment/cloud-providers) offer an option to deploy Studio alongside your serverless function. Currently, the supported providers are:
+
+- [`VercelDeployer`](https://mastra.ai/reference/deployer/vercel)
+
+### Manual
+
+You can't directly deploy the built Studio assets to a CDN, as the UI relies on some dynamic configuration. With a bit of extra setup, you can create a standalone SPA out of the built assets and deploy it to any static hosting service.
 
 Follow the example below to create a SPA using Vite.
 
@@ -212,23 +220,41 @@ Follow the example below to create a SPA using Vite.
    MASTRA_SERVER_PORT=4111
    MASTRA_SERVER_PROTOCOL=http
    MASTRA_API_PREFIX=/api
-   MASTRA_STUDIO_BASE_PATH=
-   MASTRA_TELEMETRY_DISABLED=true
    MASTRA_HIDE_CLOUD_CTA=false
-   MASTRA_TEMPLATES=false
    MASTRA_CLOUD_API_ENDPOINT=
    MASTRA_EXPERIMENTAL_FEATURES=false
+   MASTRA_TEMPLATES=false
+   MASTRA_TELEMETRY_DISABLED=true
    MASTRA_REQUEST_CONTEXT_PRESETS=
+   MASTRA_THEME_TOGGLE=false
+   MASTRA_EXPERIMENTAL_UI=false
+   MASTRA_STUDIO_BASE_PATH=
    ```
 
-   ````text
-   </StepItem>
+7. Run the build script to generate the static files in the `dist` folder:
 
-   <StepItem>
-   Run the build script to generate the static files in the `dist` folder:
+   **npm**:
 
-   ```bash npm2yarn
+   ```bash
    npm run build
-   ````
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm run build
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn build
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun run build
+   ```
 
-7. Point your hosting provider to the `dist` folder and deploy!
+8. Point your hosting provider to the `dist` folder and deploy!

package/.docs/docs/studio/observability.md

@@ -0,0 +1,98 @@
+# Studio observability
+
+Studio includes these observability views:
+
+- **Metrics** for aggregate performance data
+- **Traces** for individual request inspection
+
+All require an [observability storage backend](#quickstart) to be configured.
+
+## Metrics
+
+A dashboard that summarizes agent, workflow, and tool performance over a configurable time range (last 24 hours to 30 days). The top row shows total agent runs, model cost, token consumption, and average scorer performance. Below that, detailed cards break down model usage and cost per model, token usage per agent, trace volume with completed and error counts, latency percentiles (p50 and p95), and scorer trends over time.
+
+Visit the [metrics overview](https://mastra.ai/docs/observability/metrics/overview) for more details.
+
+> **Note:** Metrics require a separate OLAP store for observability. Relational databases like PostgreSQL, LibSQL, etc. are not supported for metrics. In-memory storage resets on restart.
+
+## Traces
+
+When you run an agent or workflow, the Observability tab displays traces that highlight the key AI operations such as model calls, tool executions, and workflow steps. Follow these traces to see how data moves, where time is spent, and what's happening under the hood.
+
+Tracing filters out low-level framework details so your traces stay focused and readable. Visit the [tracing overview](https://mastra.ai/docs/observability/tracing/overview) for more details.
+
+## Quickstart
+
+For detailed instructions, follow the [observability instructions](https://mastra.ai/docs/observability/overview). To get up and running quickly, add the `@mastra/observability` package to your project and configure it with [LibSQL](https://mastra.ai/reference/storage/libsql) and [DuckDB](https://mastra.ai/reference/vectors/duckdb) for a local development setup that supports both traces and metrics.
+
+**npm**:
+
+```bash
+npm install @mastra/observability @mastra/libsql @mastra/duckdb
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/observability @mastra/libsql @mastra/duckdb
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/observability @mastra/libsql @mastra/duckdb
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/observability @mastra/libsql @mastra/duckdb
+```
+
+Then add the following to your `src/mastra/index.ts`:
+
+```ts
+import { Mastra } from '@mastra/core/mastra'
+import { LibSQLStore } from '@mastra/libsql'
+import { DuckDBStore } from '@mastra/duckdb'
+import { MastraCompositeStore } from '@mastra/core/storage'
+import {
+  Observability,
+  DefaultExporter,
+  CloudExporter,
+  SensitiveDataFilter,
+} from '@mastra/observability'
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: 'composite-storage',
+    default: new LibSQLStore({
+      id: 'mastra-storage',
+      url: 'file:./mastra.db',
+    }),
+    domains: {
+      observability: await new DuckDBStore().getStore('observability'),
+    },
+  }),
+  observability: new Observability({
+    configs: {
+      default: {
+        serviceName: 'mastra',
+        exporters: [
+          new DefaultExporter(), // Persists traces to storage for Mastra Studio
+          new CloudExporter(), // Sends traces to Mastra Cloud (if MASTRA_CLOUD_ACCESS_TOKEN is set)
+        ],
+        spanOutputProcessors: [
+          new SensitiveDataFilter(), // Redacts sensitive data like passwords, tokens, keys
+        ],
+      },
+    },
+  }),
+})
+```
+
+## Related
+
+- [Observability overview](https://mastra.ai/docs/observability/overview)
+- [Metrics overview](https://mastra.ai/docs/observability/metrics/overview)
+- [Tracing overview](https://mastra.ai/docs/observability/tracing/overview)

package/.docs/docs/studio/overview.md

@@ -0,0 +1,127 @@
+# Studio
+
+Studio provides an interactive UI for building, testing, and managing your agents, workflows, and tools. Run it locally during development, or [deploy it](https://mastra.ai/docs/studio/deployment) to production so your team can manage agents, monitor performance, and gain insights through built-in observability.
+
+Add [authentication](https://mastra.ai/docs/studio/auth) to protect your deployed Studio with login screens, role-based access control, and permission-based UI rendering so you can control what each team member can see and do. You can also [create a project in Mastra Cloud](https://mastra.ai/docs/mastra-cloud/setup) for a hosted option.
+
+[YouTube video player](https://www.youtube-nocookie.com/embed/ojGu6Bi4wYk)
+
+## Start Studio
+
+If you created your application with `create mastra`, start the development server using the `dev` script. You can also run it directly with `mastra dev`.
+
+**npm**:
+
+```bash
+npm run dev
+```
+
+**pnpm**:
+
+```bash
+pnpm run dev
+```
+
+**Yarn**:
+
+```bash
+yarn dev
+```
+
+**Bun**:
+
+```bash
+bun run dev
+```
+
+Once the server is running, you can:
+
+- Open the Studio UI at [http://localhost:4111](http://localhost:4111/) to interact with your agents, workflows, and tools.
+- Visit <http://localhost:4111/swagger-ui> to discover and interact with the underlying REST API.
+
+To run Studio in production, see [Studio deployment](https://mastra.ai/docs/studio/deployment). To run Studio independently from your Mastra server, use [`mastra studio`](https://mastra.ai/reference/cli/mastra).
+
+## Primitives
+
+### Agents
+
+Chat with your agent directly, dynamically switch [models](https://mastra.ai/models), and tweak settings like temperature and top-p to understand how they affect the output.
+
+When you interact with your agent, you can follow each step of its reasoning, view tool call outputs, and [observe](#observability) traces and logs to see how responses are generated. You can also attach [scorers](#scorers) to measure and compare response quality over time.
+
+### Workflows
+
+Visualize your workflow as a graph and run it step by step with a custom input. During execution, the interface updates in real time to show the active step and the path taken.
+
+When running a workflow, you can also view detailed traces showing tool calls, raw JSON outputs, and any errors that might have occurred along the way.
+
+### Processors
+
+View the input and output processors attached to each agent. The agent detail panel lists every processor by name and type, so you can verify your guardrails, token limiters, and custom processors are wired up correctly before testing.
+
+See [processors](https://mastra.ai/docs/agents/processors) and [guardrails](https://mastra.ai/docs/agents/guardrails) for configuration details.
+
+### MCP servers
+
+List the MCP servers attached to your Mastra instance and explore their available tools.
+
+### Tools
+
+Run tools on their own to observe behavior and test them before assigning them to an agent. If something goes wrong, re-run a tool in isolation to debug the issue.
+
+### Workspaces
+
+Browse the files in your agent's workspace filesystem using a built-in file browser. Switch between workspace mounts, create directories, and view file contents with syntax highlighting. Writable workspaces allow directory creation and file deletion; read-only workspaces are labeled accordingly. The Skills tab lists all discovered skills with their instructions, references, and metadata. Install community skills from [skills.sh](https://skills.sh) or remove existing ones.
+
+See [workspaces](https://mastra.ai/docs/workspace/overview) for configuration details.
+
+### Request context
+
+Set runtime variables that flow into your agent's instructions and tools through dependency injection. Edit request context as JSON or use a schema-driven form when your agent defines a `requestContextSchema`. Values persist across test chats and experiments, so you can trigger conditional flows without restarting.
+
+See [request context](https://mastra.ai/docs/server/request-context) for configuration details.
+
+## Evaluation
+
+### Scorers
+
+The Scorers tab displays the results of your agent's scorers as they run. When messages pass through your agent, the defined scorers evaluate each output asynchronously and render their results here. This allows you to understand how your scorers respond to different interactions, compare performance across test cases, and identify areas for improvement.
+
+### Datasets
+
+Create and manage collections of test cases to evaluate your agents and workflows. Import items from CSV or JSON, define input and ground-truth schemas, and pin to specific versions so you can reproduce experiments exactly. Run experiments with [scorers](https://mastra.ai/docs/evals/overview) to compare quality across prompts, models, or code changes.
+
+See [datasets overview](https://mastra.ai/docs/evals/datasets/overview) for the full API and versioning details.
+
+### Experiments
+
+Run all items in a dataset against an agent, workflow, or scorer and collect the results in one place. Select a target, optionally attach scorers, and trigger the experiment. The results view shows each item's input, output, status, and individual score breakdowns. Compare two experiments side by side to measure the impact of prompt, model, or code changes.
+
+See [datasets overview](https://mastra.ai/docs/evals/datasets/overview) for setup details.
+
+## Observability
+
+Visit the [Studio observability](https://mastra.ai/docs/studio/observability) docs to learn more.
+
+## Settings
+
+Configure the connection between Studio and your Mastra server. The settings page includes:
+
+- **Mastra instance URL**: The base URL of your Mastra server (e.g. `http://localhost:4111`).
+- **API prefix**: Optional path prefix for all API requests (defaults to `/api`).
+- **Custom headers**: Add key-value pairs sent with every request, useful for authentication tokens or routing headers.
+- **Theme**: Switch between dark, light, or system theme.
+
+## Code configuration
+
+In addition to the [settings](#settings) UI, you can configure the local development server and Studio also through the [`server`](https://mastra.ai/reference/configuration) option in your `src/mastra/index.ts`.
+
+By default, Studio runs at <http://localhost:4111>. You can change the [`host`](https://mastra.ai/reference/configuration) and [`port`](https://mastra.ai/reference/configuration).
+
+Mastra also supports HTTPS development through the [`--https`](https://mastra.ai/reference/cli/mastra) flag, which automatically creates and manages certificates for your project. When you run `mastra dev --https`, a private key and certificate are generated for localhost (or your configured host). Visit the [HTTPS reference](https://mastra.ai/reference/configuration) to learn more.
+
+## Next steps
+
+- Learn how to [deploy Studio](https://mastra.ai/docs/studio/deployment) for production use.
+- Add [authentication](https://mastra.ai/docs/studio/auth) to control access to your deployed Studio.
+- Explore [Studio observability](https://mastra.ai/docs/studio/observability) to monitor agent performance and gain insights through metrics, logs, and traces.

package/.docs/docs/workflows/agents-and-tools.md

@@ -1,14 +1,14 @@
 # Agents and tools
 
-Workflow steps can call agents to leverage LLM reasoning or call tools for type-safe logic. You can either invoke them from within a step's `execute` function or compose them directly as steps using `createStep()`.
+Workflow steps can call agents to leverage LLM reasoning or call tools for type-safe logic. You can either invoke them from within a step's `execute()` function or compose them directly as steps using `createStep()`.
 
 ## Using agents in workflows
 
-Use agents in workflow steps when you need reasoning, language generation, or other LLM-based tasks. Call from a step's `execute` function for more control over the agent call (e.g., track message history or return structured output). Compose agents as steps when you don't need to modify how the agent is invoked.
+Use agents in workflow steps when you need reasoning, language generation, or other LLM-based tasks. Call from a step's `execute()` function for more control over the agent call (e.g., track message history or return structured output). Compose agents as steps when you don't need to modify how the agent is invoked.
 
 ### Calling agents
 
-Call agents inside a step's `execute` function using `.generate()` or `.stream()`. This lets you modify the agent call and handle the response before passing it to the next step.
+Call agents inside a step's `execute()` function using `.generate()` or `.stream()`. This lets you modify the agent call and handle the response before passing it to the next step.
 
 ```typescript
 const step1 = createStep({
@@ -41,7 +41,6 @@ Compose an agent as a step using `createStep()` when you don't need to modify th
 
 ```typescript
 import { testAgent } from '../agents/test-agent'
-
 const step1 = createStep(testAgent)
 
 export const testWorkflow = createWorkflow({})
@@ -111,20 +110,20 @@ The `structuredOutput.schema` option accepts any Zod schema. The agent will gene
 
 ## Using tools in workflows
 
-Use tools in workflow steps to leverage existing tool logic. Call from a step's `execute` function when you need to prepare context or process responses. Compose tools as steps when you don't need to modify how the tool is used.
+Use tools in workflow steps to leverage existing tool logic. Call from a step's `.execute()` function when you need to prepare context or process responses. Compose tools as steps when you don't need to modify how the tool is used.
 
 ### Calling tools
 
-Call tools inside a step's `execute` function using `.execute()`. This gives you more control over the tool's input context, or process its response before passing it to the next step.
+Call tools inside a step's `.execute()` function. This gives you more control over the tool's input context, or process its response before passing it to the next step.
 
 ```typescript
 import { testTool } from '../tools/test-tool'
 
 const step2 = createStep({
   execute: async ({ inputData, requestContext }) => {
-    const { formatted } = inputData
+    const { text } = inputData
 
-    const response = await testTool.execute({ text: formatted }, { requestContext })
+    const response = await testTool.execute({ text }, { requestContext })
 
     return {
       emphasized: response.emphasized,
@@ -133,8 +132,6 @@ const step2 = createStep({
 })
 ```
 
-> **Info:** Visit [Calling Tools](https://mastra.ai/docs/workflows/agents-and-tools) for more examples.
-
 ### Tools as steps
 
 Compose a tool as a step using `createStep()` when the previous step's output matches the tool's input context. You can use `.map()` to transform the previous step's output if they don't.

package/.docs/docs/workflows/control-flow.md

@@ -99,7 +99,7 @@ export const testWorkflow = createWorkflow({
   .commit()
 ```
 
-> 📹 Watch: How to run steps in parallel and optimize your Mastra workflow → [YouTube (3 minutes)](https://youtu.be/GQJxve5Hki4)
+> **📹 Watch:** How to run steps in parallel and optimize your Mastra workflow → [YouTube (3 minutes)](https://youtu.be/GQJxve5Hki4)
 
 ### Output structure
 

package/.docs/docs/workflows/overview.md

@@ -45,7 +45,7 @@ const step1 = createStep({
 })
 ```
 
-> **Info:** Visit [Step Class](https://mastra.ai/reference/workflows/step) for a full list of configuration options.
+> **Info:** Visit [`Step`](https://mastra.ai/reference/workflows/step) for a full list of configuration options.
 
 ### Using agents and tools
 
@@ -80,6 +80,15 @@ export const testWorkflow = createWorkflow({
 
 Workflows can be composed using a number of different methods. The method you choose determines how each step's schema should be structured. Visit the [Control Flow](https://mastra.ai/docs/workflows/control-flow) page for more information.
 
+## Studio
+
+Open [Studio](https://mastra.ai/docs/studio/overview) and select a workflow from the **Workflows** tab.
+
+- **Graph view**: The center panel visualizes the workflow's steps and execution flow.
+- **Input form**: The right sidebar generates a form from the workflow's `inputSchema`. Fill it in and start the run.
+- **Live status**: During execution, the graph updates each step's status in real time. The sidebar shows the workflow's input, output, state, and logs.
+- [**Time travel**](https://mastra.ai/docs/workflows/time-travel): After a run completes, replay individual steps to inspect or retry them.
+
 ## Workflow state
 
 Workflow state lets you share values across steps without passing them through every step's inputSchema and outputSchema. Use state for tracking progress, accumulating results, or sharing configuration across the entire workflow.
@@ -188,7 +197,7 @@ const testWorkflow = mastra.getWorkflow('testWorkflow')
 
 Workflows can be run in two modes: start waits for all steps to complete before returning, and stream emits events during execution. Choose the approach that fits your use case: start when you only need the final result, and stream when you want to monitor progress or trigger actions as steps complete.
 
-**Start**:
+**.start()**:
 
 Create a workflow run instance using `createRun()`, then call `.start()` with `inputData` matching the workflow's `inputSchema`. The workflow executes all steps and returns the final result.
 
@@ -206,7 +215,7 @@ if (result.status === 'success') {
 }
 ```
 
-**Stream**:
+**.stream()**:
 
 Create a workflow run instance using `.createRun()`, then call `.stream()` with `inputData` matching the workflow's `inputSchema`. Iterate over `fullStream` to track progress, then await `result` to get the final workflow result.
 
@@ -356,10 +365,6 @@ const step1 = createStep({
 
 > **Tip:** For type-safe request context schema validation, see [Schema Validation](https://mastra.ai/docs/server/request-context).
 
-## Testing with Studio
-
-Use [Studio](https://mastra.ai/docs/getting-started/studio) to run workflows with different inputs, visualize the execution lifecycle, see the inputs and outputs for each step, and inspect each part of the workflow in more detail.
-
 ## Related
 
 For a closer look at workflows, see our [Workflow Guide](https://mastra.ai/guides/guide/ai-recruiter), which walks through the core concepts with a practical example.

package/.docs/docs/workflows/suspend-and-resume.md

@@ -1,4 +1,4 @@
-# Suspend and resume
+# Suspend & resume
 
 Workflows can be paused at any step to collect additional data, wait for API callbacks, throttle costly operations, or request [human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop) input. When a workflow is suspended, its current execution state is saved as a snapshot. You can later resume the workflow from a [specific step ID](https://mastra.ai/docs/workflows/snapshots), restoring the exact state captured in that snapshot. [Snapshots](https://mastra.ai/docs/workflows/snapshots) are stored in your configured storage provider and persist across deployments and application restarts.
 

package/.docs/guides/concepts/multi-agent-systems.md

@@ -22,7 +22,7 @@ Multi-agent patterns are useful when the system needs a clear way to divide cont
 
 ## Handoffs
 
-A handoff pattern transfers control from one agent to another. Unlike a supervisor pattern, the first agent does not stay in charge for the full task. Instead, the active specialist takes ownership of the next part of the interaction.
+A handoff pattern transfers control from one agent to another. Unlike a supervisor pattern, the first agent doesn't stay in charge for the full task. Instead, the active specialist takes ownership of the next part of the interaction.
 
 Use handoffs when the next specialist should continue the interaction directly instead of reporting back through a central coordinator. The tradeoff is that context management becomes more important, since the system must decide what the next agent inherits and what remains scoped.
 
@@ -34,13 +34,13 @@ A workflow pattern defines the execution path in code. Instead of asking an agen
 
 Use workflows when the task is well understood and the execution path is known in advance. The main advantage is predictability: The system is easier to debug, reason about, and audit because the structure is explicit. The tradeoff is flexibility, since workflows are less adaptive when the task changes as it unfolds.
 
-In Mastra, [workflows](https://mastra.ai/docs/workflows/overview) can implement several coordination patterns, including handoffs and councils. What makes a workflow distinct is not which agents it calls, but that the control logic lives in the workflow itself.
+In Mastra, [workflows](https://mastra.ai/docs/workflows/overview) can implement several coordination patterns, including handoffs and councils. What makes a workflow distinct isn't which agents it calls, but that the control logic lives in the workflow itself.
 
 ## Supervisors
 
 A supervisor pattern keeps one lead agent in control for the full task. The supervisor decides when to delegate, which specialist to call, what context to pass, and how to combine the result.
 
-Use this pattern when the task is open-ended and the full sequence is not known in advance. For example, a research task may require different lines of inquiry based on what earlier steps uncover. A supervisor can adapt as the task unfolds. The tradeoff is that the supervisor becomes the main coordination point. That makes the pattern flexible, but it also means the result depends heavily on good delegation behavior and clear subagent boundaries.
+Use this pattern when the task is open-ended and the full sequence isn't known in advance. For example, a research task may require different lines of inquiry based on what earlier steps uncover. A supervisor can adapt as the task unfolds. The tradeoff is that the supervisor becomes the main coordination point. That makes the pattern flexible, but it also means the result depends heavily on good delegation behavior and clear subagent boundaries.
 
 In Mastra, this pattern maps directly to [supervisor agents](https://mastra.ai/docs/agents/supervisor-agents). A supervisor agent defines subagents on the `agents` property and uses `stream()` or `generate()` to coordinate them. Mastra also provides delegation hooks, message filtering, and memory isolation to help control this pattern.
 
@@ -52,7 +52,7 @@ A council pattern asks multiple agents to work on the same problem independently
 
 Use this pattern when the question is ambiguous, evaluative, or high-stakes and answer quality matters more than speed. The tradeoff is cost, since councils intentionally duplicate effort and usually take longer and use more tokens than other patterns.
 
-Mastra does not provide a dedicated council primitive. In Mastra, implement this pattern with [agents](https://mastra.ai/docs/agents/overview) and [workflows](https://mastra.ai/docs/workflows/overview): Run multiple agents in parallel, collect their outputs, and add a final synthesis or review step. Workflow control flow methods such as `.parallel()` provide the structure for this pattern.
+Mastra doesn't provide a dedicated council primitive. In Mastra, implement this pattern with [agents](https://mastra.ai/docs/agents/overview) and [workflows](https://mastra.ai/docs/workflows/overview): Run multiple agents in parallel, collect their outputs, and add a final synthesis or review step. Workflow control flow methods such as `.parallel()` provide the structure for this pattern.
 
 ## Choosing a pattern
 

package/.docs/guides/deployment/vercel.md

@@ -69,7 +69,7 @@ export const mastra = new Mastra({
 
 ## Studio
 
-You can deploy [Studio](https://mastra.ai/docs/getting-started/studio) alongside your API by enabling the `studio` option. Studio is deployed as static assets served from Vercel's Edge CDN, so it doesn't consume function invocations.
+You can deploy [Studio](https://mastra.ai/docs/studio/overview) alongside your API by enabling the `studio` option. Studio is deployed as static assets served from Vercel's Edge CDN, so it doesn't consume function invocations.
 
 ```typescript
 import { Mastra } from '@mastra/core'

package/.docs/guides/getting-started/next-js.md

@@ -87,7 +87,7 @@ This creates a `src/mastra` folder with an example weather agent and the followi
 
 You'll call `weather-agent.ts` from your Next.js routes in the next steps.
 
-> **Using Mastra Studio alongside Next.js:** If you want to run `mastra dev` (Mastra Studio) alongside your Next.js app and have both share the same database, update the storage URL in `src/mastra/index.ts` to use an absolute path:
+> **Using Studio alongside Next.js:** If you want to run [Studio](https://mastra.ai/docs/studio/overview) alongside your Next.js app and have both share the same database, update the storage URL in `src/mastra/index.ts` to use an absolute path:
 >
 > ```typescript
 > url: 'file:/absolute/path/to/your/project/mastra.db'