@mastra/mcp-docs-server 1.2.11 → 1.2.12-alpha.3

package/.docs/docs/server/auth/workers.md

@@ -0,0 +1,133 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Workers
+
+When workers run in separate processes from the API, they communicate over HTTP. The orchestration worker calls the API's step execution endpoint to run workflow steps on the API server. Push-mode PubSub brokers (like Google Cloud Pub/Sub in push mode) can also deliver events directly to the API's event endpoint. This is a distinct integration path from pull-mode workers, which pull events from the broker themselves. Both HTTP endpoints require authentication when an auth provider is configured.
+
+## How it works
+
+Worker authentication uses the same auth pipeline as the rest of your Mastra server. The orchestration worker sends credentials with each HTTP request, and the server's configured `authenticateToken` provider validates them.
+
+| Endpoint                                                    | Used by                                       | Purpose                            |
+| ----------------------------------------------------------- | --------------------------------------------- | ---------------------------------- |
+| `POST /api/workflows/:workflowId/runs/:runId/steps/execute` | Orchestration worker via `HttpRemoteStrategy` | Execute a workflow step on the API |
+| `POST /api/workflows/events`                                | Push-mode brokers (GCP Pub/Sub, SNS)          | Deliver workflow events to the API |
+
+Both routes have `requiresAuth: true`. When no auth provider is configured, they're publicly accessible.
+
+> **Warning:** When deploying workers as separate processes, always configure an auth provider on the server. Without one, the step execution and event endpoints are open to any caller.
+
+## Setting up worker auth
+
+### Configure an auth provider on the server
+
+Use any Mastra auth provider. `SimpleAuth` works well for worker tokens:
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { SimpleAuth } from '@mastra/core/server'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new SimpleAuth({
+      tokens: {
+        [process.env.WORKER_TOKEN!]: {
+          id: 'worker',
+          name: 'Orchestration Worker',
+          role: 'worker',
+        },
+      },
+    }),
+  },
+  // ... storage, pubsub, etc.
+})
+```
+
+### Set the worker token
+
+On each worker container, set `MASTRA_WORKER_AUTH_TOKEN` to a token that the server's auth provider recognizes:
+
+```yaml
+services:
+  api:
+    environment:
+      WORKER_TOKEN: ${WORKER_TOKEN}
+      # ... other env vars
+
+  orchestration-worker:
+    environment:
+      MASTRA_WORKER_AUTH_TOKEN: ${WORKER_TOKEN}
+      MASTRA_STEP_EXECUTION_URL: http://api:4111/api
+      # ... other env vars
+```
+
+```bash
+WORKER_TOKEN=sk-worker-secret-token
+```
+
+The orchestration worker reads `MASTRA_WORKER_AUTH_TOKEN` and sends it as a `Bearer` token in the `Authorization` header on every step execution request.
+
+## Auth credential types
+
+The `HttpRemoteStrategy` supports three credential formats. The default (`bearer`) covers most setups.
+
+### Bearer token
+
+Set `MASTRA_WORKER_AUTH_TOKEN` and the strategy sends `Authorization: Bearer <token>`:
+
+```bash
+MASTRA_WORKER_AUTH_TOKEN=sk-worker-secret-token
+```
+
+### API key header
+
+Send the credential as `x-worker-api-key` instead of `Authorization`:
+
+```typescript
+import { HttpRemoteStrategy } from '@mastra/core/worker'
+
+const strategy = new HttpRemoteStrategy({
+  serverUrl: 'http://api:4111/api',
+  auth: { type: 'api-key', key: process.env.WORKER_API_KEY! },
+})
+```
+
+Your server's auth provider must read the `x-worker-api-key` header to validate this credential.
+
+### Custom header
+
+Use any header name and value:
+
+```typescript
+import { HttpRemoteStrategy } from '@mastra/core/worker'
+
+const strategy = new HttpRemoteStrategy({
+  serverUrl: 'http://api:4111/api',
+  auth: {
+    type: 'header',
+    name: 'X-Internal-Service-Key',
+    value: process.env.INTERNAL_KEY!,
+  },
+})
+```
+
+## Push-mode broker authentication
+
+When using a push-mode PubSub (like Google Cloud Pub/Sub), the broker POSTs events directly to the `/api/workflows/events` endpoint. The broker attaches its own credentials. For example, Google Cloud Pub/Sub sends a Google-signed OIDC token.
+
+Your auth provider's `authenticateToken` callback must recognize whatever credential the broker sends. See your broker's documentation for the authentication scheme it uses.
+
+## Security recommendations
+
+- **Use different tokens for different worker types.** This lets you revoke access to one worker without affecting others.
+- **Rotate tokens on a schedule.** Update the `WORKER_TOKEN` environment variable and restart the affected containers.
+- **Use TLS in production.** Worker-to-API communication should go over HTTPS to protect tokens in transit. Within a private network (Docker bridge, Kubernetes cluster), plain HTTP is acceptable.
+- **Restrict network access.** The step execution and event endpoints are internal. If possible, keep them off the public internet using network policies or firewall rules.
+
+## Related
+
+- [Auth overview](https://mastra.ai/docs/server/auth): Available auth providers and how they work
+- [Token-based auth](https://mastra.ai/docs/server/auth/simple-auth): Token-to-user mapping authentication
+- [Worker deployment](https://mastra.ai/guides/deployment/mastra-workers): Set up split worker processes
+- [Workers reference](https://mastra.ai/reference/workers/overview): Configuration details for all worker types
+- [CLI reference](https://mastra.ai/reference/cli/mastra): `mastra worker build` and `mastra worker start`

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

@@ -42,7 +42,7 @@ You must implement these six abstract methods. Each handles a specific part of t
 
 ### `registerContextMiddleware()`
 
-This method runs first and attaches Mastra context to every incoming request. Route handlers need access to the Mastra instance, tools, and other context to function. How you attach this context depends on your framework — Express uses `res.locals`, Hono uses `c.set()`, and other frameworks have their own patterns.
+This method runs first and attaches Mastra context to every incoming request. Route handlers need access to the Mastra instance, tools, and other context to function. How you attach this context depends on your framework, Express uses `res.locals`, Hono uses `c.set()`, and other frameworks have their own patterns.
 
 ```typescript
 registerContextMiddleware(): void {
@@ -152,7 +152,7 @@ async registerRoute(
 
 ### `getParams()`
 
-Extract URL parameters, query parameters, and request body from the incoming request. Different frameworks expose these values in different ways—Express uses `req.params`, `req.query`, and `req.body`, while other frameworks may use different property names or require method calls. This method normalizes the extraction for your framework.
+Extract URL parameters, query parameters, and request body from the incoming request. Different frameworks expose these values in different ways, Express uses `req.params`, `req.query`, and `req.body`, while other frameworks may use different property names or require method calls. This method normalizes the extraction for your framework.
 
 ```typescript
 async getParams(
@@ -294,7 +294,7 @@ See [Server Adapters](https://mastra.ai/docs/server/server-adapters) for full do
 
 ## Full example
 
-Here's a skeleton implementation showing all the required methods. This uses pseudocode for framework-specific parts—replace with your framework's actual APIs:
+Here's a skeleton implementation showing all the required methods. This uses pseudocode for framework-specific parts, replace with your framework's actual APIs:
 
 ```typescript
 import { MastraServer, ServerRoute } from '@mastra/server/server-adapter'
@@ -369,7 +369,7 @@ await server.init()
 app.listen(4111)
 ```
 
-> **Tip:** The existing [@mastra/hono](https://github.com/mastra-ai/mastra/blob/main/server-adapters/hono/src/index.ts) and [@mastra/express](https://github.com/mastra-ai/mastra/blob/main/server-adapters/express/src/index.ts) implementations are good references when building your custom adapter. They show how to handle framework-specific patterns for context storage, middleware registration, and response handling.
+> **Tip:** The existing [@mastra/hono](https://github.com/mastra-ai/mastra/blob/main/server-adapters/hono/src/index.ts) and [@mastra/express](https://github.com/mastra-ai/mastra/blob/main/server-adapters/express/src/index.ts) implementations are good references when building your custom adapter. They show how to handle framework-specific patterns for context storage and middleware registration, plus response handling.
 >
 > If you want to use [Studio](https://mastra.ai/docs/studio/overview) with your server adapter, use [`mastra studio`](https://mastra.ai/reference/cli/mastra) to only launch the Studio UI.
 

package/.docs/docs/server/mastra-client.md

@@ -138,7 +138,7 @@ Visit [MastraClient](https://mastra.ai/reference/client-js/mastra-client) for mo
 
 ## Credentials and session cookies
 
-**Authenticate Mastra API calls with session cookies** when your UI and Mastra API aren't on the same origin—different host, subdomain, or port (for example Mastra Studio on one port and a custom server on another). Add **`credentials: 'include'`** to `MastraClient` so each request carries the cookies the user already has after sign-in. Skip this and you will often get **`401`** responses from Mastra even though login succeeded in the browser.
+**Authenticate Mastra API calls with session cookies** when your UI and Mastra API aren't on the same origin, different host, subdomain, or port (for example Mastra Studio on one port and a custom server on another). Add **`credentials: 'include'`** to `MastraClient` so each request carries the cookies the user already has after sign-in. Skip this and you will often get **`401`** responses from Mastra even though login succeeded in the browser.
 
 ```typescript
 import { MastraClient } from '@mastra/client-js'
@@ -149,7 +149,7 @@ export const mastraClient = new MastraClient({
 })
 ```
 
-**Allow credentialed cross-origin requests on your server**—see [CORS: requests with credentials](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS#requests_with_credentials). You need a concrete `Access-Control-Allow-Origin` (not `*`) and `Access-Control-Allow-Credentials: true`, or the browser will block the call before it reaches Mastra.
+**Allow credentialed cross-origin requests on your server**, see [CORS: requests with credentials](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS#requests_with_credentials). You need a concrete `Access-Control-Allow-Origin` (not `*`) and `Access-Control-Allow-Credentials: true`, or the browser will block the call before it reaches Mastra.
 
 **Using `@mastra/react`?** Wrap your app with `MastraReactProvider`, set `baseUrl` and `apiPrefix` to match your server, and rely on the default `credentials: 'include'`. Change `credentials` only when you want `same-origin` or `omit` behavior.
 
@@ -237,7 +237,7 @@ export const colorAgent = new Agent({
   instructions: `You are a helpful CSS assistant.
   You can change the background color of web pages.
   Respond with a hex reference for the color requested by the user`,
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
 })
 ```
 

package/.docs/docs/server/mastra-server.md

@@ -14,7 +14,7 @@ Mastra runs as an HTTP server that exposes your agents, workflows, and other fun
 - **[Server Adapters](https://mastra.ai/docs/server/server-adapters)**: Run Mastra with Express, Hono, or your own HTTP server instead of the generated server.
 - **[Custom Adapters](https://mastra.ai/docs/server/custom-adapters)**: Build adapters for frameworks not officially supported.
 - **[Mastra Client SDK](https://mastra.ai/docs/server/mastra-client)**: Type-safe client for calling agents, workflows, and tools from browser or server environments.
-- **[A2A](https://mastra.ai/docs/agents/a2a)**: Expose agents through A2A agent cards, task streams, and push notifications.
+- **[A2A](https://mastra.ai/docs/agents/a2a)**: Expose agents through A2A agent cards and task streams, plus push notifications.
 - **[Authentication](https://mastra.ai/docs/server/auth)**: Secure endpoints with JWT, Clerk, Supabase, Firebase, Auth0, or WorkOS.
 
 ## Configuration
@@ -47,7 +47,7 @@ The server provides:
 - API endpoints for all registered agents and workflows
 - Custom API routes and middleware
 - Authentication across providers
-- Request context for dynamic configuration
+- Request context for runtime configuration
 - Stream data redaction for secure responses
 
 ## REST API

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

@@ -56,7 +56,7 @@ registerApiRoute('/my-custom-route', {
 
 ### Using `RequestContext`
 
-You can populate `RequestContext` dynamically in server middleware by extracting information from the request. In this example, the `temperature-unit` is set based on the Cloudflare `CF-IPCountry` header to ensure responses match the user's locale.
+You can populate `RequestContext` in a runtime server middleware by extracting information from the request. In this example, the `temperature-unit` is set based on the Cloudflare `CF-IPCountry` header to ensure responses match the user's locale.
 
 ```typescript
 import { Mastra } from '@mastra/core'

package/.docs/docs/server/pubsub.md

@@ -2,7 +2,7 @@
 
 # PubSub
 
-Mastra uses a publish/subscribe (pub/sub) system as its internal event bus. Components publish events to named topics, and other components subscribe to those topics to react. The backend you configure decides how far those events travel: within one process, across processes on one host, or across separate instances.
+Mastra uses a publish/subscribe (pub/sub) system as its internal event bus. Components publish events to topics, and other components subscribe to those topics to react. The backend you configure decides how far those events travel: within one process or across processes on one host, or alternatively across separate instances.
 
 You set the backend once on the `Mastra` instance, and the rest of the system uses it without changes. By default, Mastra uses an in-process backend that needs no setup.
 
@@ -25,7 +25,7 @@ Backends deliver events in one of two modes, defined by the [`PubSub`](https://m
 - **Pull**: Consumers read from the backend on their own, which Mastra does with a long-lived worker loop. Distributed backends such as [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams) use this mode.
 - **Push**: Events arrive without the consumer asking, either in process or over HTTP. The default [`EventEmitterPubSub`](https://mastra.ai/reference/pubsub/event-emitter) delivers this way in process.
 
-Subscribers can also opt into work distribution. A group of subscribers that share a consumer group split the events between them, so each event is handled once. Subscribers without a group each receive every event, which fans the stream out to all of them.
+Subscribers can also distribute work through consumer groups. Members of the same group split the events so each event is handled once. A subscriber without a group receives every event, which fans the stream out to all ungrouped subscribers.
 
 ## Default backend
 
@@ -68,7 +68,9 @@ export const mastra = new Mastra({
 
 ### Distributed deployments
 
-Use a distributed backend when you run more than one instance or host, so every instance receives the same events. This matters whenever a request handled by one instance must reach work running on another. For example, sending a signal to an agent run requires the signal event to cross the process boundary to the instance that owns the run. With the in-process default, that instance never receives the event.
+Use a distributed backend when you run more than one instance or host, so every instance receives the same events. This matters whenever a request handled by one instance must reach work running on another.
+
+For example, sending a signal to an agent run requires the signal event to cross the process boundary to the instance that owns the run. With the in-process default, that instance never receives the event.
 
 Both backends below deliver across processes and hosts and persist events for redelivery.
 
@@ -123,4 +125,5 @@ Visit the [PubSub reference](https://mastra.ai/reference/pubsub/base) for the fu
 - [PubSub reference](https://mastra.ai/reference/pubsub/base)
 - [Mastra class](https://mastra.ai/reference/core/mastra-class)
 - [Background task streaming](https://mastra.ai/docs/long-running-agents/background-tasks)
-- [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows)
+- [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows)
+- [Workers](https://mastra.ai/docs/deployment/workers): Run workflow orchestration and background tasks in dedicated processes using PubSub

package/.docs/docs/server/request-context.md

@@ -6,7 +6,7 @@ Agents, tools, and workflows can all accept `RequestContext` as a parameter, mak
 
 ## When to use `RequestContext`
 
-Use `RequestContext` when a primitive's behavior should change based on runtime conditions. For example, you might switch models or storage backends based on user attributes, or adjust instructions and tool selection based on language.
+Use `RequestContext` when a primitive's behavior should change based on runtime conditions. For example or you might switch models or storage backends based on user attributes, or alternatively adjust instructions and tool selection based on language.
 
 > **Note:** `RequestContext` is primarily used for passing data into specific requests. It's distinct from agent memory, which handles conversation history and state persistence across multiple calls.
 
@@ -58,7 +58,7 @@ await weatherTool.execute({ location: 'London' }, { requestContext })
 
 ### Setting values based on request headers
 
-You can populate `requestContext` dynamically in server middleware by extracting information from the request. In this example, the `temperature-unit` is set based on the Cloudflare `CF-IPCountry` header to ensure responses match the user's locale.
+You can populate `requestContext` in a runtime server middleware by extracting information from the request. In this example, the `temperature-unit` is set based on the Cloudflare `CF-IPCountry` header to ensure responses match the user's locale.
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -86,7 +86,7 @@ Visit [Middleware](https://mastra.ai/docs/server/middleware) for how to use serv
 
 ## Studio
 
-When developing locally, you can define named presets in a JSON file and load them into [Studio](https://mastra.ai/docs/studio/overview) with the [`--request-context-presets`](https://mastra.ai/reference/cli/mastra) CLI flag. This adds a dropdown to the request context editor in Studio so you can quickly switch between configurations without manually editing JSON each time.
+When developing locally, you can define presets in a JSON file and load them into [Studio](https://mastra.ai/docs/studio/overview) with the [`--request-context-presets`](https://mastra.ai/reference/cli/mastra) CLI flag. This adds a dropdown to the request context editor in Studio so you can quickly switch between configurations without manually editing JSON each time.
 
 ```bash
 mastra dev --request-context-presets ./presets.json
@@ -129,7 +129,7 @@ You can also use `requestContext` with other options like `agents`, `workflows`,
 
 ### Dynamic instructions
 
-Agent instructions can be provided as an async function, enabling you to resolve prompts dynamically at runtime. Combined with `requestContext`, this enables patterns like:
+Agent instructions can be provided as an async function, enabling you to resolve prompts at runtime. Combined with `requestContext`, this enables patterns like:
 
 - **Personalization**: Tailor instructions based on user attributes, preferences, or tier
 - **Localization**: Adjust tone, language, or behavior based on locale
@@ -157,13 +157,13 @@ export const dynamicAgent = new Agent({
 
     return `${basePrompt} ${localeInstructions}`.trim()
   },
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
 })
 ```
 
 #### Fetching from a prompt registry
 
-If your organization uses a prompt registry service for central prompt management, you can fetch instructions at runtime. This allows you to update prompts without redeploying, run experiments with variants, and track prompt usage across your agents.
+If your organization uses a prompt registry service for central prompt management, you can fetch instructions at runtime. You can update prompts without redeploying and run experiments with variants, plus track prompt usage across your agents.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -184,7 +184,7 @@ export const registryAgent = new Agent({
 
     return prompt.content
   },
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
 })
 ```
 
@@ -247,7 +247,7 @@ auth: {
 }
 ```
 
-When the resource ID is derived this way, clients can omit `memory.resource` from agent generate and stream request bodies — the server-derived value is used instead (and always takes precedence over any client-provided value). If a request uses memory and neither the body nor the request context provides a resource ID, the server responds with a 400 error.
+When the resource ID is derived this way, clients can omit `memory.resource` from agent generate and stream request bodies, the server-derived value is used instead (and always takes precedence over any client-provided value). If a request uses memory and neither the body nor the request context provides a resource ID, the server responds with a 400 error.
 
 You can also set these keys manually in middleware:
 
@@ -312,7 +312,7 @@ for (const [key, value] of ctx.entries()) {
 
 ## Schema validation
 
-Use `requestContextSchema` to define a [Standard JSON Schema](https://standardschema.dev/json-schema) ([Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/), etc.) that validates request context values at runtime. This catches missing or invalid context values early, provides clear error messages, and gives you type inference within your component.
+Use `requestContextSchema` to define a [Standard JSON Schema](https://standardschema.dev/json-schema) ([Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/), etc.) that validates request context values at runtime. This catches missing or invalid context values early and provides clear error messages, plus gives you type inference within your component.
 
 ### Agent schema validation
 
@@ -340,7 +340,7 @@ export const validatedAgent = new Agent({
 
     return `You are helping user ${userId}`
   },
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
 })
 ```
 
@@ -453,7 +453,7 @@ Steps can also define their own `requestContextSchema` for step-level validation
 
 ### Best practices
 
-**Match your middleware**: Define the same required fields in your schema that your middleware sets. This ensures the contract between middleware and components is explicit and validated.
+**Match your middleware**: Define the same required fields in your schema that your middleware sets. As a result, the contract between middleware and components is explicit and validated.
 
 ```typescript
 // Middleware sets these fields

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

@@ -10,7 +10,7 @@ Server adapters let you run Mastra with your own HTTP server instead of the Hono
 - You need direct access to the server instance for custom configuration
 - Your team prefers using another server framework instead of the Hono server created by `mastra build`.
 
-> **Tip:** 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](https://mastra.ai/docs/server/mastra-server).
+> **Tip:** For deployments without custom server requirements, use `mastra build` instead. It configures server setup and registers middleware, plus applies deployment settings based on your project configuration. See [Server Configuration](https://mastra.ai/docs/server/mastra-server).
 >
 > If you want to use [Studio](https://mastra.ai/docs/studio/overview) with your server adapter, use [`mastra studio`](https://mastra.ai/reference/cli/mastra) to only launch the Studio UI.
 
@@ -517,7 +517,7 @@ See [MastraServer](https://mastra.ai/reference/server/mastra-server) for full co
 
 ## Per-route auth overrides
 
-When authentication is configured on your Mastra instance, all routes require authentication by default. Sometimes you need exceptions: public health check endpoints, webhook receivers, or admin routes that need stricter controls.
+When authentication is configured on your Mastra instance, all routes require authentication by default. Sometimes you need exceptions: public health check endpoints or webhook receivers, or alternatively admin routes that need stricter controls.
 
 Use `customRouteAuthConfig` to override authentication behavior for specific routes. Keys follow the format `METHOD:PATH` where method is `GET`, `POST`, `PUT`, `DELETE`, or `ALL`. Paths support wildcards (`*`) for matching multiple routes. Setting a value to `false` makes the route public, while `true` requires authentication.
 

package/.docs/docs/storage/overview.md

@@ -14,7 +14,7 @@ Storage powers:
 
 ## When to configure storage
 
-Configure a persistent storage adapter when state must survive restarts, be shared across processes, or be visible in Studio across sessions. The default in-memory store is useful for tests and short local experiments, but it loses data when the process exits.
+Configure a persistent storage adapter when state must survive restarts or be shared across processes. Persistent storage also keeps state visible in Studio across sessions. The default in-memory store is useful for tests and short local experiments, but it loses data when the process exits.
 
 Use storage when your application needs any of these behaviors:
 
@@ -144,7 +144,7 @@ export const supportAgent = new Agent({
   id: 'support-agent',
   name: 'Support agent',
   instructions: 'Answer customer support questions.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   memory: new Memory({
     storage: new PostgresStore({
       id: 'support-agent-storage',

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

@@ -9,7 +9,7 @@ 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.
+- Permissions must restrict who can execute agents or edit workflows, or alternatively delete datasets.
 - A login screen (SSO, email/password, or both) should gate access to your Studio deployment.
 
 ## Quickstart
@@ -64,7 +64,7 @@ Studio handles the token as follows:
 - It removes `auth_header` from the address bar while preserving other query parameters and the hash.
 - It keeps the token in memory only and never writes it to local storage, so the token stays transient and doesn't persist across page reloads.
 
-The token rides in a URL parameter, so the host application is responsible for how that URL is generated and transmitted. URL parameters can be exposed through browser history, referrer headers, and server access logs.
+The token rides in a URL parameter, so the host application is responsible for how that URL is generated and transmitted. URL parameters can be exposed through browser history and referrer headers, plus server access logs.
 
 ## Role-based access control
 
@@ -72,7 +72,7 @@ RBAC lets you control what each user can see and do inside Studio. It's separate
 
 ### Default roles
 
-Mastra ships four default roles. Import them from `@mastra/core/auth/ee`:
+Mastra includes four default roles. Import them from `@mastra/core/auth/ee`:
 
 | Role     | Permissions              |
 | -------- | ------------------------ |
@@ -106,7 +106,7 @@ export const mastra = new Mastra({
 })
 ```
 
-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.
+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
 
@@ -153,7 +153,7 @@ Sign-up can be enabled or disabled per provider. When disabled, Studio hides the
 
 ## 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.
+Studio Auth features (SSO login, RBAC, permission-based UI) are part of the Mastra Enterprise Edition. A license is optional when using Simple Auth or running locally. Production deployments with third-party providers require a valid EE license from [Mastra sales](https://mastra.ai/contact).
 
 ## Related
 

package/.docs/docs/studio/deployment.md

@@ -99,7 +99,7 @@ Some of the [Cloud providers](https://mastra.ai/docs/deployment/cloud-providers)
 
 ### 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.
+You can't directly deploy the built Studio assets to a CDN, as the UI relies on some runtime 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.
 

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

@@ -98,11 +98,11 @@ When you run an agent or workflow, the Observability tab displays traces that hi
 
 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.
 
-To export a trace, select **Download trace JSON** in the trace panel header. This saves the entire trace as a `trace-<id>.json` file, with every span and its full input, output, metadata, and attributes. Use it to share a trace, attach it to a bug report, or build an evaluation dataset offline.
+To export a trace, select **Download trace JSON** in the trace panel header. This saves the entire trace as a `trace-<id>.json` file, with every span and its full input, output, metadata, and attributes. Use it to share a trace or attach it to a bug report, or alternatively build an evaluation dataset offline.
 
 ## Logs
 
-Browse internal Mastra logs forwarded to your observability storage. Logs provide full-text search (across message content, entity names, and trace IDs), date presets (last 24 hours to 30 days), and multi-select filters for level, entity type, and entity name. Selecting a log opens a detail panel showing the full message, structured data, and metadata. If the log is correlated with a trace, you can navigate directly to the trace and span timeline.
+Browse internal Mastra logs forwarded to your observability storage. Logs provide full-text search (across message content, entity names, and trace IDs), date presets (last 24 hours to 30 days), and multi-select filters for level, entity type, and entity name. Selecting a log opens a detail panel showing the full message, structured data, and metadata. If the log is correlated with a trace, you can move through directly to the trace and span timeline.
 
 Log forwarding is enabled by default when you configure observability. See [logging](https://mastra.ai/docs/observability/logging) for level configuration, query examples, and customization details.
 

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

@@ -2,7 +2,7 @@
 
 # Studio
 
-Studio provides an interactive UI for building, testing, and managing your agents, workflows, and tools. Run it locally during development, add [authentication](https://mastra.ai/docs/studio/auth), 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.
+Studio provides an interactive UI for building, testing, and managing your agents, workflows, and tools. Run it locally during development, add [authentication](https://mastra.ai/docs/studio/auth), or [deploy it](https://mastra.ai/docs/studio/deployment) to production so your team can manage agents and monitor performance, plus gain insights through built-in observability.
 
 > **📹 Watch:** Watch [Mastra Studio overview](https://youtu.be/ojGu6Bi4wYk) for a short walkthrough of building, testing, and managing agents in Studio.
 
@@ -49,23 +49,25 @@ When you're ready to share Studio with your team, you can deploy it to productio
 
 ### 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.
+Chat with your agent directly, 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.
+When you interact with your agent, you can follow its reasoning and view tool call outputs. You can also [observe](#observability) traces and logs to see how responses are generated.
 
-While an agent response is streaming, you can send a follow-up message in the same thread. Studio shows the message as pending until the stream confirms it, then continues the response below that follow-up. Other Studio tabs that have the same thread open can observe the active stream.
+You can also attach [scorers](#scorers) to measure and compare response quality over time.
 
-Use [Editor](https://mastra.ai/docs/editor/overview) to let non-technical team members iterate on agents, version every change, and run experiments without redeploying.
+You can send a follow-up message in the same thread during an agent response stream. Studio shows the message as pending until the stream confirms it, then continues the response below that follow-up. Other Studio tabs that have the same thread open can observe the active stream.
+
+Use [Editor](https://mastra.ai/docs/editor/overview) to let non-technical team members iterate on agents and version every change, plus run experiments without redeploying.
 
 ### 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.
+When running a workflow, you can also view detailed traces showing tool calls and raw JSON outputs, plus 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.
+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 and token limiters, plus 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.
 
@@ -95,11 +97,11 @@ Use the date filter to limit score metrics to a preset or custom time range.
 
 ### 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.
+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. You can understand how your scorers respond to different interactions and compare performance across test cases, plus 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.
+Create and manage collections of test cases to evaluate your agents and workflows. Import items from CSV or JSON and define input and ground-truth schemas, plus 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.