@mastra/mcp-docs-server 1.2.15-alpha.15 → 1.2.15-alpha.20

package/.docs/docs/agents/code-mode.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.38.0`
 
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 Code mode lets an agent run multi-tool computations in an isolated sandbox and return the result as a single, more accurate response.
 
@@ -164,9 +164,24 @@ const { tool, instructions } = createCodeMode(
 
 `isolated-vm` is a native addon, and on Node.js 20 and later the host process must be started with the `--no-node-snapshot` flag. See the [IsolatedVmCodeModeTransport reference](https://mastra.ai/reference/tools/isolated-vm-transport) for setup details.
 
+When the host can't install native addons or set Node.js flags, which is common on serverless platforms, use [`QuickJsCodeModeTransport`](https://mastra.ai/reference/tools/quickjs-transport) from `@mastra/quickjs` instead. It gives the same in-process boundary using a QuickJS runtime compiled to WebAssembly, at the cost of slower execution:
+
+```typescript
+import { createCodeMode } from '@mastra/core/tools'
+import { QuickJsCodeModeTransport } from '@mastra/quickjs'
+
+const { tool, instructions } = createCodeMode(
+  { tools }, // no sandbox needed
+  new QuickJsCodeModeTransport({ memoryLimitMb: 128 }),
+)
+```
+
+See [Choosing a transport](https://mastra.ai/reference/tools/quickjs-transport) for a side-by-side comparison.
+
 ## Related
 
 - [createCodeMode() reference](https://mastra.ai/reference/tools/create-code-mode)
 - [IsolatedVmCodeModeTransport reference](https://mastra.ai/reference/tools/isolated-vm-transport)
+- [QuickJsCodeModeTransport reference](https://mastra.ai/reference/tools/quickjs-transport)
 - [Tools](https://mastra.ai/docs/agents/using-tools)
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)

package/.docs/docs/agents/processors.md

@@ -432,7 +432,7 @@ See the [`ProviderHistoryCompat` reference](https://mastra.ai/reference/processo
 
 ## Response caching
 
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 Response caching skips the LLM call and replays a previously cached response when an agent receives an identical request. Use it to reduce latency and avoid paying for repeated calls.
 
@@ -544,7 +544,7 @@ This means the cache key is derived from the resolved `LanguageModelV2Prompt` Ma
 
 When you don't supply `key`, the processor derives one deterministically from the inputs that change the LLM's response at this step: `agentId`, `stepNumber` (so each step in a tool loop has its own cache entry), `scope`, model identity (`provider`, `modelId`, spec version), and the resolved `prompt` (post-memory + post-processors). Any change to these inputs automatically invalidates the cache.
 
-Multimodal prompts are included too. Image and file parts reach the key by value: a URL contributes its full href, and inline binary data (`Uint8Array`, `ArrayBuffer`) contributes a digest of its bytes. Two requests that differ only in which image they reference therefore get different cache entries.
+Multimodal prompts are included too. Image and file parts reach the key by value: the key includes a URL's full href, and a digest of the bytes for inline binary data (`Uint8Array`, `ArrayBuffer`). Requests that differ only in which image they reference therefore get different cache entries.
 
 #### Customize the cache key
 
@@ -664,7 +664,7 @@ export class SteeringReminderProcessor implements Processor {
 }
 ```
 
-A transient signal still appears in the prompt for the current call, so the model sees it near the latest turn. It's not retained, so re-sending it each turn keeps a single fresh copy in context instead of an accumulating history, and it never appears in stored thread history. Because nothing is written, it also keeps a stable prompt cache prefix across turns.
+A transient signal is still in the prompt for the current call, so the model sees it near the latest turn. It's not retained, so re-sending it each turn keeps a single fresh copy in context instead of an accumulating history, and stored thread history never includes it. Because nothing is written, it also keeps a stable prompt cache prefix across turns.
 
 ### Emit custom stream events
 

package/.docs/docs/browser/recording.md

@@ -1,12 +1,12 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Browser recording (beta)
+# Browser recording
 
 **Added in:** `@mastra/core@1.43.0`
 
 Browser recording adds two opt-in tools that let an agent save a browser session as a Motion-JPEG AVI video. The agent can also add short captions while it works.
 
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 ## When to use browser recording
 

package/.docs/docs/deployment/workers.md

@@ -2,7 +2,7 @@
 
 # Workers
 
-> **Beta:** This feature is in beta. The API is stable enough for production use, but some details may change. See [known limitations](#known-limitations) for current gaps.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable. See [known limitations](#known-limitations) for current gaps.
 
 Workers handle background processing outside the request-response cycle. Workflow step execution, cron-based scheduling, and long-running tool calls all run in workers, keeping the API responsive.
 

package/.docs/docs/getting-started/develop.md

@@ -138,7 +138,7 @@ See the [project structure reference](https://mastra.ai/reference/project-struct
 
 ## File-based agents
 
-> **Beta:** File-based agents are in beta and may change before they're stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 >
 > File-based discovery only runs through `mastra dev` or `mastra build`. If your app imports `mastra` directly, including through a web framework or server adapter, file-based agents aren't discovered. Register those agents in code or run Mastra as a separate server.
 

package/.docs/docs/harness/agent-controller.md

@@ -2,7 +2,7 @@
 
 # AgentController
 
-> **Beta:** The [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class) feature is in beta stage and subject to breaking changes in minor versions until it graduates from its beta status.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 `AgentController` is a shared runtime host for interactive agent applications. It coordinates modes, models, storage, workspaces, tool approvals, subagents, and channels. Each user or active task works through an isolated [`Session`](https://mastra.ai/reference/agent-controller/session).
 
@@ -343,7 +343,48 @@ Point each platform webhook at the controller-specific route:
 
 Each external chat thread maps to one controller Session and Mastra thread. By default, new sessions use a resource ID derived from the adapter's chat-thread ID, prefixed with `channel:`. Use `resolveResourceId` to map direct messages to an existing application user or choose another memory owner. The callback only affects new threads; an existing thread keeps its stored resource ID.
 
-Channel sessions are created by the controller rather than by your code, so `onSessionStart` is where you configure them. It runs once per session, after the session is bound to its mapped thread and before the first message is handled. Use it to apply a model, memory settings, or session state that a channel session would otherwise miss. Later messages in the same thread reuse the session and don't call it again. Errors are logged and swallowed so a session that can't be configured still answers the message.
+Channel sessions are created by the controller rather than by your code, so `onSessionStart` is where you configure them. It runs once per session, after the session is bound to its mapped thread and before the first message is handled. A channel session starts with controller defaults, so this is where you set its model and memory settings. Later messages in the same thread reuse the session and don't call it again. Errors are logged and swallowed so a session that can't be configured still answers the message.
+
+### Authorize and route channel sessions
+
+`onSessionStart` runs after the session exists and swallows errors, so it can't refuse a request. Use `resolveSession` when your host decides whether a session may exist. It replaces the built-in session creation and runs before any session exists. Throwing refuses the request before the controller creates a session or calls the model. Mastra logs the refusal and leaves the chat thread silent, so your authorization message never reaches the channel.
+
+```typescript
+channels: {
+  adapters: { slack: createSlackAdapter() },
+  resolveSession: async ({ controller, thread, requestContext }) => {
+    const install = await installs.authorize(requestContext.get('teamId'))
+
+    return controller.createSession({
+      resourceId: thread.resourceId,
+      scope: install.id,
+      ownerId: controller.id,
+      requestContext,
+    })
+  },
+}
+```
+
+Create the session under `thread.resourceId`. A session can only bind threads it owns, so use `resolveResourceId` if you want a different owner for the mapped thread. Sessions are get-or-create per `resourceId` and `scope`, so pass `scope` when one thread needs separate sessions per install or principal.
+
+Failures that aren't refusals (a storage outage, a bug in your resolver's dependencies) still post an error to the thread, so a broken bot doesn't look like a silent one. If you need to tell them apart in your own code, a refusal is a `ChannelSessionRejectedError` with the original error as its `cause`.
+
+`resolveSession` also runs when a user answers an approval card, with that action's request context, so a shared install revalidates the person approving rather than trusting the person who sent the original message.
+
+### Handle stale approvals
+
+An approval gate lives in memory, so every approval answered after a restart is stale. Mastra never runs the tool for a stale action. Use `onStaleToolApproval` to settle the attempt the user answered, instead of dropping it:
+
+```typescript
+channels: {
+  adapters: { slack: createSlackAdapter() },
+  onStaleToolApproval: async ({ decision, toolCallId, runId, memory }) => {
+    await runs.markInterrupted({ runId, toolCallId, decision, threadId: memory.thread })
+  },
+}
+```
+
+`runId` is the run the approval card was rendered for, which is the attempt the user answered and the one you settle against after a restart. The session's own run is passed separately as `currentRunId`, and is usually `null` or a different run by then.
 
 Controller channel sessions and auto-approval state are held in memory, so use a long-lived server. Pending approvals and live Session state don't survive process restarts. Adapters that can't render approval controls automatically run tools without an approval prompt so the run doesn't remain suspended.
 

package/.docs/docs/harness/overview.md

@@ -4,12 +4,10 @@
 
 A harness lets an agent pursue long-running, complex goals while keeping its work durable, visible, and steerable. It preserves progress across retries and interruptions, while giving people and other systems a way to inspect progress, add context, approve actions, redirect the agent, or stop it.
 
-In Mastra, harness refers to a set of capabilities for managing an agent beyond a single uninterrupted run. You can adopt these capabilities individually or combine them as needed.
-
-[`AgentController`](https://mastra.ai/docs/harness/agent-controller) is a harness designed for interactive agent applications. It extends the base [`Agent`](https://mastra.ai/docs/agents/overview) loop with isolated sessions for each user or task, persistent threads and state, switchable modes and models, tool permissions and approvals, subagent orchestration, and streams for events and display state.
-
 Agent harnesses are useful wherever work continues over time. Common examples include coding agents that carry changes through CI and review, software factories that coordinate many tasks in parallel, SRE agents that adapt as incidents evolve, and go-to-market agents that respond as accounts, signals, and conversations change.
 
+In Mastra, harness refers to a set of capabilities for managing an agent beyond a single uninterrupted run. You can adopt these capabilities individually or combine them as needed.
+
 ## When to use a harness
 
 Choose a starting point based on what the agent needs. You may use one capability or several.

package/.docs/docs/long-running-agents/durable-agents.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.45.0`
 
-> **Warning:** Durable agents are currently in **beta**. APIs may change in future releases.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 A durable agent wraps a regular [`Agent`](https://mastra.ai/docs/agents/overview) so the agentic loop runs inside a workflow. Events flow through [PubSub](https://mastra.ai/docs/server/pubsub), which means a client can disconnect and reconnect without missing chunks. The run state is persisted, so it survives process restarts.
 

package/.docs/docs/long-running-agents/goals.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.42.0`
 
-> **Beta:** The Goals feature is in beta stage and subject to breaking changes in minor versions until it graduates from its beta status.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 A goal is a durable, thread-scoped objective: a standing instruction the agent keeps working toward across loop iterations until a judge model decides it's satisfied or a run budget is exhausted.
 

package/.docs/docs/long-running-agents/schedules.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.50.0`
 
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 A schedule runs an agent on a cron cadence. On each fire, Mastra sends a prompt to the agent, either as a [signal](https://mastra.ai/docs/long-running-agents/signals) into a thread or as a threadless [`agent.generate()`](https://mastra.ai/reference/agents/generate) run. Use schedules for recurring agent work such as daily summaries, periodic checks, or scheduled nudges into a conversation.
 

package/.docs/docs/long-running-agents/signal-providers.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.39.0`
 
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 A signal provider monitors an external source, such as GitHub, Slack, continuous integration (CI), or your own API, and pushes [notification signals](https://mastra.ai/docs/long-running-agents/signals) into subscribed agent threads.
 

package/.docs/docs/long-running-agents/signals.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.39.0`
 
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 Signals are a way to interact with an agent through a thread. Instead of starting every interaction with `agent.stream()`, subscribe to a thread and send messages or signals. Mastra either wakes the agent when the thread is idle or drops input into the running agent loop, or alternatively queues input for the next turn.
 

package/.docs/docs/mastra-platform/deploy.md

@@ -132,6 +132,33 @@ mastra deploy --env staging --env-file .env.staging
 
 To change variables on a running service without a redeploy, update them in the dashboard and run [`mastra env restart`](https://mastra.ai/reference/cli/mastra).
 
+## Private npm packages
+
+Projects that depend on packages from a private registry install them during the deploy using the standard `NPM_TOKEN` contract.
+
+1. Store a read-only registry token as `NPM_TOKEN` on the project or environment through the dashboard.
+
+2. Commit a token-free `.npmrc` that points your scope at the registry and reads the token from the environment:
+
+   ```ini
+   @your-org:registry=https://npm.pkg.github.com
+   //npm.pkg.github.com/:_authToken=${NPM_TOKEN}
+   ```
+
+   Keep the `${NPM_TOKEN}` reference literal. The package manager resolves it at install time, so the token itself never lands in your repository.
+
+3. Deploy as usual:
+
+   ```bash
+   mastra deploy
+   ```
+
+In a monorepo, a `.npmrc` in your project directory takes precedence over one at the repository root.
+
+`NPM_TOKEN` is available during dependency installation. Mastra redacts its value from the Mastra source-build logs that it streams. The generated Dockerfile receives it as a build argument, so the runtime image stays free of the token. `NPM_TOKEN` is also injected into the running service as a regular environment variable, so treat it as a secret your application can read.
+
+Projects without a private-registry `.npmrc` need no changes. When your `.npmrc` references `${NPM_TOKEN}`, set the variable or the dependency install fails.
+
 ## Project resolution
 
 Every deploy resolves its target project in this order:

package/.docs/docs/mastra-platform/trace-intelligence.md

@@ -56,12 +56,9 @@ The flow chart connects themes in adjacent trace signal columns:
 
 The flow shows association, not causation or execution order. For example, a ribbon between a Goal and an Outcome means that both themes occurred in the same traces. It doesn't show that the goal caused the outcome.
 
-### Distributions, Other, and Noise
+### Other and Noise
 
-The cards below the flow show each trace signal's theme distribution:
-
-- **Trace count**: The number of distinct traces assigned to a theme in the selected snapshot.
-- **Stage share**: The percentage of analyzed traces for that trace signal assigned to the theme.
+Each node shows its trace count: the number of distinct traces assigned to that theme in the selected snapshot. A theme's details also state its share, for example "28 of 70 traces in this snapshot (40%)".
 
 Studio shows the most common themes for each trace signal type. It may combine smaller themes into **Other** to preserve totals without overcrowding the chart.
 
@@ -69,26 +66,25 @@ Studio shows the most common themes for each trace signal type. It may combine s
 
 ### Snapshots
 
-A snapshot is a moving analysis window over a set of traces. Snapshots can overlap, so don't add their trace counts together. Compare trace count and stage share together because traffic volume can change between windows.
+A snapshot is a moving analysis window over a set of traces. Snapshots can overlap, so don't add their trace counts together. Compare a theme's trace count and its share of the snapshot together because traffic volume can change between windows.
 
 A theme can persist, disappear, split, merge, or return across snapshots. Treat theme names and descriptions as generated summaries, not fixed taxonomies.
 
 ## Use the Trace Intelligence page
 
 1. Use the **Agent** selector to switch between agents with available analysis. An agent doesn't appear until its first themes are ready.
-2. Select a theme in the flow to filter every column to traces containing that theme.
-3. Select **View theme details** to inspect its description, trace count, stage share, generated examples, and history.
+2. Select a theme in the flow to open its details and filter every column to traces containing that theme.
+3. The details panel shows the theme's description, its share of the snapshot, paged example summaries, and a trend of its trace count over time.
 4. Select **Clear filter** to restore the complete flow.
 
 You can also:
 
-- Select a theme in a distribution card to open its details and generated example summaries.
-- Select **Noise** in a distribution card to inspect its distribution and generated example summaries.
-- Drag the distribution cards to reorder the trace signal columns and see a different relationship perspective.
+- Select **Noise** in the flow to inspect its share and generated example summaries.
+- Drag the column headers above the chart to reorder the trace signal columns and see a different relationship perspective.
 - Use the timeline to select a snapshot, or select **Play** to watch themes change over time.
-- Open a theme's history to see whether it persisted and how its coverage changed.
+- Switch to **Compare** to see which themes grew, shrank, entered the range, or left the range between two points in time, or **Lifelines** to follow each theme's share across the whole selected range.
 
-Filtering the flow by a theme is unavailable for snapshots with more than 2,000 traces. Choose another snapshot or clear the active filter to return to the full flow. Theme and Noise details remain available from the distribution cards.
+Filtering the flow by a theme is unavailable for snapshots with more than 2,000 traces. Selecting a theme still opens its details there without filtering the flow.
 
 ## Troubleshooting
 

package/.docs/docs/memory/message-history.md

@@ -6,7 +6,7 @@ Message history is the most basic and important form of memory. It gives the LLM
 
 You can also retrieve message history to display past conversations in your UI.
 
-> **Info:** Each message belongs to a thread (the conversation) and a resource (the user or entity it's associated with). See [Threads and resources](#threads-and-resources) for more detail.
+> **Note:** Each message belongs to a thread (the conversation) and a resource (the user or entity it's associated with). See [Threads and resources](#threads-and-resources) for more detail.
 
 > **Warning:** When you use memory with a client application, send **only the new message** from the client instead of the full conversation history.
 >
@@ -113,7 +113,7 @@ await agent.stream('Hello', {
 })
 ```
 
-> **Info:** Threads and messages are created automatically when you call `agent.generate()` or `agent.stream()`, but you can also create them manually with [`createThread()`](https://mastra.ai/reference/memory/createThread) and [`saveMessages()`](https://mastra.ai/reference/memory/memory-class).
+> **Note:** Threads and messages are created automatically when you call `agent.generate()` or `agent.stream()`, but you can also create them manually with [`createThread()`](https://mastra.ai/reference/memory/createThread) and [`saveMessages()`](https://mastra.ai/reference/memory/memory-class).
 
 You can use this history in two ways:
 

package/.docs/docs/observability/integrations/exporters/mastra-platform.md

@@ -186,7 +186,7 @@ When you deploy with Mastra Studio, set **Deployment → Service Name** to a sta
 
 ## Performance
 
-> **Info:** MastraPlatformExporter uses batching to optimize network usage. Events are buffered and sent in batches, reducing overhead while maintaining near real-time visibility.
+> **Note:** MastraPlatformExporter uses batching to optimize network usage. Events are buffered and sent in batches, reducing overhead while maintaining near real-time visibility.
 
 ### Batching behavior
 

package/.docs/docs/observability/integrations/exporters/otel.md

@@ -230,7 +230,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Info:** Get your Dash0 endpoint from your dashboard. It should be in the format `ingress.{region}.aws.dash0.com:4317`.
+> **Note:** Get your Dash0 endpoint from your dashboard. It should be in the format `ingress.{region}.aws.dash0.com:4317`.
 
 ### `SigNoz`
 
@@ -400,7 +400,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Info:** The Datadog Agent must be configured with OTLP ingestion enabled. Add the following to your `datadog.yaml`:
+> **Note:** The Datadog Agent must be configured with OTLP ingestion enabled. Add the following to your `datadog.yaml`:
 >
 > ```yaml
 > otlp_config:

package/.docs/docs/server/auth/auth0.md

@@ -200,7 +200,7 @@ export const createMastraClient = (accessToken: string) => {
 }
 ```
 
-> **Info:** The access token must be prefixed with `Bearer` in the Authorization header.
+> **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
 >
 > Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
 

package/.docs/docs/server/auth/clerk.md

@@ -61,7 +61,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Info:** The default `authorizeUser` method allows all authenticated users. To customize user authorization, provide a custom `authorizeUser` function when constructing the provider.
+> **Note:** The default `authorizeUser` method allows all authenticated users. To customize user authorization, provide a custom `authorizeUser` function when constructing the provider.
 >
 > Visit [MastraAuthClerk](https://mastra.ai/reference/auth/clerk) for all available configuration options.
 
@@ -105,7 +105,7 @@ export const mastraClient = new MastraClient({
 })
 ```
 
-> **Info:** The access token must be prefixed with `Bearer` in the Authorization header.
+> **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
 >
 > Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
 

package/.docs/docs/server/auth/firebase.md

@@ -200,7 +200,7 @@ export const createMastraClient = (idToken: string) => {
 }
 ```
 
-> **Info:** The ID token must be prefixed with `Bearer` in the Authorization header.
+> **Note:** The ID token must be prefixed with `Bearer` in the Authorization header.
 >
 > Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
 

package/.docs/docs/server/auth/okta.md

@@ -179,16 +179,35 @@ export const mastraClient = new MastraClient({
 
 ### Bearer token
 
-You can also pass an Okta access token as a Bearer token. The token is verified against Okta's JWKS endpoint:
+You can also pass an Okta token as a Bearer token. The token is verified against Okta's JWKS endpoint, and its `aud` claim must match the configured audience. The audience defaults to your client ID, and you can override it with the `audience` option or `OKTA_AUDIENCE`.
+
+Okta puts the client ID in the `aud` claim of **ID tokens**, so ID tokens work with the default. **Access tokens** carry the audience of the authorization server that issued them, so set the audience to match:
+
+- **Org authorization server** (the default, issuer `https://{domain}`): set the audience to `https://{domain}`.
+- **Custom authorization server** (issuer `https://{domain}/oauth2/{name}`): set the audience to the server's audience value from the Okta Admin Console, for example `api://default`.
+
+```env
+OKTA_AUDIENCE=https://dev-123456.okta.com
+```
+
+Pass an array to accept more than one audience, for example ID tokens from browsers and access tokens from service callers against the same provider:
+
+```typescript
+new MastraAuthOkta({
+  audience: ['your-client-id', 'https://dev-123456.okta.com'],
+})
+```
+
+> **Note:** `audience` applies only to Bearer tokens. The ID token exchanged during the SSO login flow is always verified against your client ID.
 
 ```typescript
 import { MastraClient } from '@mastra/client-js'
 
-export const createMastraClient = (accessToken: string) => {
+export const createMastraClient = (token: string) => {
   return new MastraClient({
     baseUrl: 'http://localhost:4111',
     headers: {
-      Authorization: `Bearer ${accessToken}`,
+      Authorization: `Bearer ${token}`,
     },
   })
 }
@@ -213,7 +232,7 @@ console.log(response)
 ```bash
 curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
   -H "Content-Type: application/json" \
-  -H "Authorization: Bearer <your-okta-access-token>" \
+  -H "Authorization: Bearer <your-okta-token>" \
   -d '{
     "messages": "Weather in London"
   }'
@@ -222,6 +241,7 @@ curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
 ## Troubleshooting
 
 - **401 on every request**: Verify your Okta domain, client ID, and client secret are correct. Check that the redirect URI in your Okta application matches `OKTA_REDIRECT_URI`.
+- **401 with `unexpected "aud" claim value` in the server logs**: The Bearer token's audience doesn't match the configured audience. This usually means you sent an access token while the audience is still the default client ID. Set `OKTA_AUDIENCE` to the audience of the authorization server that issued the token. See [Bearer token](#bearer-token).
 - **Cookies not sent cross-origin**: Set `credentials: "include"` in `MastraClient` and configure `server.cors` with your frontend origin and `credentials: true`.
 - **Session lost on restart**: Set `OKTA_COOKIE_PASSWORD` to a stable value (at least 32 characters). Without it, an auto-generated key is used that changes on each restart.
 - **RBAC returns empty permissions**: Verify `OKTA_API_TOKEN` is set and the token has permission to list user groups. Check that group names in `roleMapping` match your Okta group names exactly.

package/.docs/docs/server/auth/supabase.md

@@ -59,7 +59,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Info:** The default `authorizeUser` method checks the `isAdmin` column in the `users` table in the `public` schema. To customize user authorization, provide a custom `authorizeUser` function when constructing the provider.
+> **Note:** The default `authorizeUser` method checks the `isAdmin` column in the `users` table in the `public` schema. To customize user authorization, provide a custom `authorizeUser` function when constructing the provider.
 >
 > Visit [MastraAuthSupabase](https://mastra.ai/reference/auth/supabase) for all available configuration options.
 
@@ -101,7 +101,7 @@ export const mastraClient = new MastraClient({
 })
 ```
 
-> **Info:** The access token must be prefixed with `Bearer` in the Authorization header.
+> **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
 >
 > Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
 

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

@@ -2,6 +2,8 @@
 
 # Workers
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 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

package/.docs/docs/server/auth/workos.md

@@ -221,7 +221,7 @@ export const createMastraClient = (accessToken: string) => {
 }
 ```
 
-> **Info:** The access token must be prefixed with `Bearer` in the Authorization header.
+> **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
 >
 > Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
 

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

@@ -6,7 +6,7 @@ Create a custom adapter when the prebuilt server adapters (Hono, Express, Fastif
 
 A custom adapter translates between Mastra's route definitions and your framework's routing system. You'll implement methods that register middleware, handle requests, and send responses using your framework's APIs.
 
-> **Info:** Use any of these prebuilt server adapters:
+> **Note:** Use any of these prebuilt server adapters:
 >
 > - [@mastra/hono](https://mastra.ai/reference/server/hono-adapter)
 > - [@mastra/express](https://mastra.ai/reference/server/express-adapter)

package/.docs/docs/server/custom-api-routes.md

@@ -35,6 +35,41 @@ curl http://localhost:4111/my-custom-route
 
 Each route's handler receives the Hono `Context`. Within the handler you can access the `Mastra` instance to fetch or call agents and workflows.
 
+## Schema validation
+
+Use [`createRoute()`](https://mastra.ai/reference/server/create-route) in `apiRoutes` to parse and validate path parameters, query parameters, and request bodies with Zod. The schemas also infer the handler parameters and generate OpenAPI metadata.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { createRoute } from '@mastra/server/server-adapter'
+import { z } from 'zod'
+
+const createItemRoute = createRoute({
+  method: 'POST',
+  path: '/items',
+  responseType: 'json',
+  bodySchema: z.object({
+    name: z.string().min(1),
+  }),
+  responseSchema: z.object({
+    id: z.string(),
+    name: z.string(),
+  }),
+  handler: async ({ name }) => ({
+    id: crypto.randomUUID(),
+    name,
+  }),
+})
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [createItemRoute],
+  },
+})
+```
+
+By default, Mastra returns a `400` response when validation fails. The `onValidationError` callback can override the status and response body. Validated values and the `Mastra` server context are passed directly to the handler.
+
 ## Middleware
 
 To add route-specific middleware pass a `middleware` array when calling `registerApiRoute()`.

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

@@ -149,7 +149,7 @@ const testAgent = async () => {
 }
 ```
 
-> **Info:** You can also call `.generate()` with an array of message objects that include `role` and `content`. Visit the [.generate() reference](https://mastra.ai/reference/client-js/agents) for more information.
+> **Note:** You can also call `.generate()` with an array of message objects that include `role` and `content`. Visit the [.generate() reference](https://mastra.ai/reference/client-js/agents) for more information.
 
 ## Streaming responses
 
@@ -175,7 +175,7 @@ const testAgent = async () => {
 }
 ```
 
-> **Info:** You can also call `.stream()` with an array of message objects that include `role` and `content`. Visit the [.stream() reference](https://mastra.ai/reference/client-js/agents) for more information.
+> **Note:** You can also call `.stream()` with an array of message objects that include `role` and `content`. Visit the [.stream() reference](https://mastra.ai/reference/client-js/agents) for more information.
 
 ## Configuration options
 

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

@@ -4,7 +4,7 @@
 
 Mastra runs as an HTTP server that exposes your agents, workflows, and other functionality as API endpoints. The server handles request routing, middleware execution, authentication, and streaming responses.
 
-> **Info:** This page covers the [`server`](https://mastra.ai/reference/configuration) configuration options passed to the `Mastra` constructor. For running Mastra with your own HTTP server (Hono, Express, etc.), visit [Server Adapters](https://mastra.ai/docs/server/server-adapters).
+> **Note:** This page covers the [`server`](https://mastra.ai/reference/configuration) configuration options passed to the `Mastra` constructor. For running Mastra with your own HTTP server (Hono, Express, etc.), visit [Server Adapters](https://mastra.ai/docs/server/server-adapters).
 
 ## Server features
 

package/.docs/docs/workflows/dynamic-workflows.md

@@ -2,7 +2,7 @@
 
 # Dynamic workflows
 
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 Dynamic workflows are workflow definitions expressed as data instead of code. A definition is a JSON document that describes the workflow's schemas and step graph. Mastra validates the definition and registers it as a runnable workflow, then persists it in storage so it survives process restarts.
 

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

@@ -287,7 +287,7 @@ You can run workflows from agents, tools, the Mastra Client, or the command line
 const testWorkflow = mastra.getWorkflow('testWorkflow')
 ```
 
-> **Info:** `mastra.getWorkflow()` is preferred over a direct import for two reasons:
+> **Note:** `mastra.getWorkflow()` is preferred over a direct import for two reasons:
 >
 > 1. It provides access to the Mastra instance configuration (logger, telemetry, storage, registered agents, and vector stores)
 > 2. It provides full TypeScript type inference for workflow input and output schemas

package/.docs/docs/workflows/time-travel.md

@@ -15,6 +15,8 @@ When you call `timeTravel()` on a workflow run:
 3. Execution begins from the specified step with the provided or reconstructed input data
 4. The workflow continues to completion from that point forward
 
+If the workflow definition has changed since the run was recorded (for example, a step was renamed), or the recorded run never reached a step that precedes the target, time travel fails with a descriptive error before anything executes, and the stored snapshot is left unchanged.
+
 Time travel requires storage to be configured since it relies on persisted workflow snapshots.
 
 ## Basic usage