@mastra/mcp-docs-server 1.1.35-alpha.8 → 1.1.36-alpha.1

package/.docs/course/03-agent-memory/18-advanced-configuration-semantic-recall.md

@@ -1,6 +1,6 @@
-# Advanced Configuration of Semantic Recall
+# Advanced configuration of semantic recall
 
-We can configure semantic recall in more detail by setting options for the `semanticRecall` option:
+Configure semantic recall with the `semanticRecall` option:
 
 ```typescript
 const memory = new Memory({
@@ -19,11 +19,55 @@ const memory = new Memory({
         before: 2,
         after: 1,
       },
+      scope: 'resource', // Search all threads for this resource
+      filter: { projectId: { $eq: 'project-a' } },
     },
   },
 })
 ```
 
-The `topK` parameter controls how many semantically similar messages are retrieved. A higher value will retrieve more messages, which can be helpful for complex topics but may also include less relevant information. The default value is `4`.
+The `topK` parameter controls how many similar messages Mastra retrieves. A higher value retrieves more messages, which can help with complex topics but may include less relevant information. The default value is `4`.
 
-The `messageRange` parameter controls how much context is included with each match. This is important because the matching message alone might not provide enough context to understand the conversation. Including messages before and after the match helps the agent understand the context of the matched message.
+The `messageRange` parameter controls how much context Mastra includes with each match. Messages before and after the match help the agent understand the matched message.
+
+The `scope` parameter controls whether Mastra searches the current thread (`'thread'`) or all threads owned by a resource (`'resource'`). Use `scope: 'resource'` to let the agent recall information from past conversations for the same resource.
+
+The `filter` parameter restricts semantic recall results to messages with matching thread metadata, such as a project ID or category.
+
+Filters match metadata stored on message embeddings when messages are saved. If thread metadata changes later, existing embeddings keep their previous metadata until those messages are saved or indexed again.
+
+Supported filter operators:
+
+- `$and`: Logical AND
+- `$eq`: Equal to
+- `$gt`: Greater than
+- `$gte`: Greater than or equal
+- `$in`: In array
+- `$lt`: Less than
+- `$lte`: Less than or equal
+- `$ne`: Not equal to
+- `$nin`: Not in array
+- `$or`: Logical OR
+
+The following example demonstrates metadata filters for common use cases:
+
+```typescript
+// Filter by project
+const options = {
+  semanticRecall: { filter: { projectId: { $eq: 'my-project' } } },
+}
+
+// Filter by multiple categories
+const options = {
+  semanticRecall: { filter: { category: { $in: ['work', 'research'] } } },
+}
+
+// Filter by project and priority
+const options = {
+  semanticRecall: {
+    filter: {
+      $and: [{ projectId: { $eq: 'project-a' } }, { priority: { $gte: 3 } }],
+    },
+  },
+}
+```

package/.docs/docs/agents/background-tasks.md

@@ -127,10 +127,12 @@ When a tool call dispatches as a background task, two streams may surface lifecy
 | `background-task-completed` | The task finished successfully. The `payload.result` matches the eventual tool result. | Manager stream |
 | `background-task-failed`    | The task threw or timed out.                                                           | Manager stream |
 | `background-task-cancelled` | The task was cancelled before completing.                                              | Manager stream |
+| `background-task-suspended` | The tool called `suspend()` from inside its execute.                                   | Manager stream |
+| `background-task-resumed`   | A suspended task was resumed via `manager.resume(taskId, resumeData)`.                 | Manager stream |
 
-`agent.stream().fullStream` only emits the agent-loop chunks (`background-task-started`, `background-task-progress`) on its own. `agent.streamUntilIdle()` emits the same two chunks and additionally subscribes to the manager pubsub for the run's memory scope and pipes the five manager chunks (`background-task-running`, `background-task-output`, `background-task-completed`, `background-task-failed`, `background-task-cancelled`) into the same `fullStream`, so consumers of `streamUntilIdle().fullStream` see all seven types.
+`agent.stream().fullStream` only emits the agent-loop chunks (`background-task-started`, `background-task-progress`) on its own. `agent.streamUntilIdle()` emits the same two chunks and additionally subscribes to the manager pubsub for the run's memory scope and pipes the seven manager chunks (`background-task-running`, `background-task-output`, `background-task-completed`, `background-task-failed`, `background-task-cancelled`, `background-task-suspended`, `background-task-resumed`) into the same `fullStream`.
 
-`backgroundTaskManager.stream()` only emits the five manager chunks.
+`backgroundTaskManager.stream()` only emits the seven manager chunks.
 
 The full payload shapes are documented in the [background task chunks reference](https://mastra.ai/reference/streaming/ChunkType).
 
@@ -210,6 +212,64 @@ When this `researchAgent` is delegated to from a supervisor that has no backgrou
 
 Use this pattern when you want a subagent to behave consistently in the background regardless of which supervisor invokes it. Use the supervisor-side opt-in (above) when you want to tune background behavior centrally per supervisor.
 
+## Suspending and resuming
+
+A background task can pause itself mid-execution and wait for an external signal before continuing. This is useful for human approvals, webhooks, or any flow where the next step depends on data that arrives later.
+
+A tool calls `suspend(data)` from inside its `execute`, which:
+
+- Persists `status: 'suspended'` and the `data` payload on the task record.
+- Saves the workflow snapshot so the run survives process restarts.
+- Emits a `background-task-suspended` chunk on the manager stream.
+- Releases the concurrency slot so other tasks can run.
+
+Resume the task with `mastra.backgroundTaskManager.resume(taskId, resumeData)`. The `resumeData` arrives in the tool's `execute` options on the resumed run, and the task transitions back to `running`.
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const reviewTool = createTool({
+  id: 'review',
+  description: 'Submit a draft for human review.',
+  inputSchema: z.object({ draft: z.string() }),
+  outputSchema: z.object({ approvedBy: z.string(), edits: z.string().optional() }),
+  background: { enabled: true },
+  execute: async ({ draft }, context) => {
+    const { suspend, resumeData } = context.agent
+    if (!resumeData) {
+      await suspend?.({ awaiting: 'approval', draft })
+      return { approvedBy: '', edits: undefined }
+    }
+    const { reviewer, edits } = resumeData as { reviewer: string; edits?: string }
+    return { approvedBy: reviewer, edits }
+  },
+})
+```
+
+The first invocation of `execute` sees `resumeData === undefined` and calls `suspend`. After the task is resumed, the runtime restarts the tool with `resumeData` populated; the `if` branch falls through and the tool returns its real result.
+
+To resume the task once an approval arrives:
+
+```typescript
+await mastra.backgroundTaskManager?.resume(taskId, {
+  reviewer: 'alice@example.com',
+  edits: 'Reworded paragraph 3.',
+})
+```
+
+### What happens to the agent loop
+
+When a task suspends mid-`streamUntilIdle()`, the wrapper treats it as terminal for the current iteration and closes. To continue the agent immediately when the resume payload is in hand, call `agent.resumeStreamUntilIdle(resumeData, { runId, toolCallId, memory })`: the resumed bg task runs to completion, its result lands in the message list, and the agent runs a follow-up turn — all on the same SSE connection. If you'd rather drive the resume out-of-band, call `mastra.backgroundTaskManager.resume(taskId, resumeData)` directly and the result still writes into the thread for the next user turn to pick up.
+
+### Re-registering the executor on resume
+
+The manager keeps tool executors in process memory. If the process restarts while a task is suspended, the executor closure is gone — the caller of `resume()` must re-register it first via `manager.registerTaskContext(taskId, ...)`. Tasks dispatched and resumed inside the same process don't need this.
+
+### Cancelling a suspended task
+
+`manager.cancel(taskId)` works against suspended tasks the same way it works for running ones: the row flips to `cancelled`, the workflow snapshot is cleaned up, and a `task.cancelled` event fires.
+
 ## Lifecycle callbacks
 
 Each layer can register terminal-state callbacks. They don't replace one another, and success/failure hooks fire for their respective outcomes:

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

@@ -11,7 +11,7 @@ You can use individual [`Processor`](https://mastra.ai/reference/processors/proc
 
 Some processors implement both input and output logic and can be used in either array depending on where the transformation should occur.
 
-Some built-in processors also persist hidden system reminder messages using `<system-reminder>...</system-reminder>` text plus `metadata.systemReminder`. These reminders stay available in raw memory history and retry/prompt reconstruction paths, but standard UI-facing message conversions and default memory recall hide them unless you explicitly opt in.
+Some built-in processors also send hidden system reminder signals. These signals are persisted in raw memory history and converted to `<system-reminder>...</system-reminder>` context before the next model call, but standard UI-facing message conversions and default memory recall hide them unless you explicitly opt in.
 
 ## When to use processors
 
@@ -391,6 +391,14 @@ new ToolCallFilter({
 })
 ```
 
+Set `preserveModelOutput: true` to keep compact `toModelOutput` history for filtered completed tool results. The filter keeps only the model-facing output and removes raw tool args and raw results.
+
+```typescript
+new ToolCallFilter({
+  preserveModelOutput: true,
+})
+```
+
 See the [`ToolCallFilter` reference](https://mastra.ai/reference/processors/tool-call-filter) for configuration options and the [Memory Processors](https://mastra.ai/docs/memory/memory-processors) page for pre-memory filtering.
 
 ### `ToolSearchProcessor`

package/.docs/docs/agents/response-caching.md

@@ -0,0 +1,148 @@
+# Response caching
+
+Response caching skips the LLM call and replays a previously cached response when an agent receives an identical request. Use it to drop latency to single-digit milliseconds and avoid paying for repeated calls.
+
+Caching is implemented as the [`ResponseCache`](https://mastra.ai/reference/processors/response-cache) input processor. There is no agent-level option — to enable caching, register the processor explicitly. This keeps the API surface small while we collect feedback; per-call overrides flow through `RequestContext`.
+
+## When to use response caching
+
+Reach for it when the same request shape repeats across users or sessions, for example prompt templates, suggested-prompt buttons, agentic search re-asks, or guardrail LLMs that classify the same input over and over. Skip it when calls trigger external side effects through tools, since cache hits replay tool calls without re-executing them.
+
+## Quickstart
+
+Add a `ResponseCache` to the agent's `inputProcessors` and pass any `MastraServerCache` as the backend. For development, `InMemoryServerCache` works out of the box:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { InMemoryServerCache } from '@mastra/core/cache'
+import { ResponseCache } from '@mastra/core/processors'
+
+const cache = new InMemoryServerCache()
+
+export const searchAgent = new Agent({
+  name: 'Search Agent',
+  instructions: 'You answer questions concisely.',
+  model: 'openai/gpt-5',
+  inputProcessors: [new ResponseCache({ cache, ttl: 600 })], // 10 minutes
+})
+```
+
+The first call runs the LLM normally and writes the response to the cache. Subsequent calls with an identical resolved prompt return the cached response without invoking the LLM.
+
+## Per-call overrides via RequestContext
+
+Per-call config flows through `RequestContext`. Use `ResponseCache.context()` to build a fresh context, or `ResponseCache.applyContext()` to merge into one you already have:
+
+```typescript
+import { ResponseCache } from '@mastra/core/processors'
+import { RequestContext } from '@mastra/core/request-context'
+
+// Fresh context with the override
+await agent.stream('hello', {
+  requestContext: ResponseCache.context({ key: 'custom-key', bust: true }),
+})
+
+// Or merge into an existing context
+const ctx = new RequestContext()
+ctx.set('caller-meta', { userId: 'u-123' })
+ResponseCache.applyContext(ctx, { bust: true })
+await agent.stream('hello', { requestContext: ctx })
+```
+
+Three fields are overridable per call:
+
+- `key` — string or function. Overrides the auto-derived cache key for this request only.
+- `scope` — string or `null`. Overrides the tenant/user scope for this request only. `null` opts out of scoping.
+- `bust` — boolean. Skips the cache read but still writes on completion (useful for "force refresh" buttons).
+
+`cache`, `ttl`, and `agentId` stay on the constructor — they are instance-level concerns and not safe to vary per call.
+
+## Tenant scoping
+
+By default, `ResponseCache` looks up `MASTRA_RESOURCE_ID_KEY` on the request context and uses it as the cache scope. This means an agent that already populates the resource id (e.g. via memory) gets per-user isolation automatically — two users never see each other's cached responses.
+
+Override explicitly when you need a different scope:
+
+```typescript
+new Agent({
+  // ...
+  inputProcessors: [
+    new ResponseCache({
+      cache,
+      scope: 'org-123', // explicit tenant scope
+    }),
+  ],
+})
+```
+
+Pass `scope: null` to deliberately share entries across all callers — only use this for known-public, non-personalized content.
+
+## Custom cache backend
+
+`ResponseCache` accepts any `MastraServerCache`. For production, use `RedisCache` from `@mastra/redis`:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { ResponseCache } from '@mastra/core/processors'
+import { RedisCache } from '@mastra/redis'
+
+const cache = new RedisCache({ url: process.env.REDIS_URL })
+
+export const agent = new Agent({
+  name: 'Cached Agent',
+  instructions: '...',
+  model: 'openai/gpt-5',
+  inputProcessors: [new ResponseCache({ cache })],
+})
+```
+
+For a custom backend, extend `MastraServerCache` and implement its abstract methods (the processor only calls `get` and `set`).
+
+## How caching is implemented
+
+`ResponseCache` hooks into `processLLMRequest` (cache lookup, short-circuits on hit) and `processLLMResponse` (cache write on completion). Both run inside the agentic loop _after_ memory has loaded and earlier input processors have transformed the prompt.
+
+This means the cache key is derived from the resolved `LanguageModelV2Prompt` Mastra is about to send to the model — i.e. _after_ memory has loaded and earlier input processors have run — and each step in an agentic tool loop is independently cached.
+
+## What's in the cache key
+
+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.
+
+### Customize the cache key
+
+Pass `key` as a function on the constructor or per-call to derive your own cache key from any subset of those inputs. The function receives the same inputs the deterministic hash would have consumed and returns a string (or a `Promise<string>`):
+
+```typescript
+import { ResponseCache, buildResponseCacheKey } from '@mastra/core/processors'
+
+await agent.stream(input, {
+  requestContext: ResponseCache.context({
+    // Cache only on the model id and the resolved prompt tail — ignore
+    // step number, scope, etc.
+    key: ({ model, prompt }) => `qa:${model.modelId}:${JSON.stringify(prompt).slice(-200)}`,
+  }),
+})
+
+// Or reuse the deterministic helper while overriding individual fields:
+await agent.stream(input, {
+  requestContext: ResponseCache.context({
+    key: inputs => buildResponseCacheKey({ ...inputs, scope: 'global' }),
+  }),
+})
+```
+
+If the function throws, the processor falls back to the default key derivation so the call still benefits from caching.
+
+## How cache hits work
+
+When the processor finds a cache hit, it short-circuits the LLM call by returning the cached chunks from `processLLMRequest`. The agentic loop synthesizes a stream from those chunks instead of calling the model. `agent.generate()` collects them into a `FullOutput`; `agent.stream()` returns a `MastraModelOutput` whose chunks come from the cached buffer, so consumers iterating `fullStream` or awaiting `text`, `usage`, and `finishReason` see the cached values.
+
+Cache writes happen after the response completes. Failed runs (errors, tripwire activations) are not cached, so the next call retries cleanly.
+
+## Related
+
+- [`ResponseCache` reference](https://mastra.ai/reference/processors/response-cache)
+- [Processors](https://mastra.ai/docs/agents/processors)
+- [Guardrails](https://mastra.ai/docs/agents/guardrails)
+- [Agent.stream()](https://mastra.ai/reference/streaming/agents/stream)
+- [Agent.generate()](https://mastra.ai/reference/agents/generate)

package/.docs/docs/agents/signals.md

@@ -0,0 +1,151 @@
+# Signals
+
+> **Experimental:** Agent signals are experimental. The API may change in a future release.
+
+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 signals. Mastra either wakes the agent when the thread is idle or drops the signal into the running agent loop.
+
+Signals are a context engineering tool for guiding the agent in real time as the agent loop progresses. Use them to add system-generated content from external event sources, such as incoming email notifications, GitHub pull request comments, background task notifications, and similar events.
+
+## Quickstart
+
+Subscribe to the thread before sending signals. The subscription receives the active stream when the signal wakes the agent or enters a running loop.
+
+```typescript
+const subscription = await agent.subscribeToThread({
+  resourceId: 'user_123',
+  threadId: 'thread_456',
+})
+
+agent.sendSignal(
+  {
+    type: 'user-message',
+    contents: 'Compare that with the previous option.',
+  },
+  {
+    resourceId: 'user_123',
+    threadId: 'thread_456',
+  },
+)
+
+for await (const chunk of subscription.stream) {
+  console.log(chunk)
+}
+```
+
+When the thread has a running agent stream, the signal becomes new input inside that agent loop. When the thread is idle, Mastra starts a stream with the signal as the first input.
+
+## Control signal behavior
+
+By default, Mastra delivers signals to active runs and wakes idle threads. Use `ifActive.behavior` and `ifIdle.behavior` to change that behavior.
+
+```typescript
+const result = agent.sendSignal(
+  {
+    type: 'user-message',
+    contents: 'Store this for later, but do not wake the agent.',
+  },
+  {
+    resourceId: 'user_123',
+    threadId: 'thread_456',
+    ifIdle: {
+      behavior: 'persist',
+    },
+  },
+)
+
+await result.persisted
+```
+
+The behavior options are:
+
+- `ifActive.behavior: 'deliver'`: Add the signal to the running agent loop. This is the default.
+- `ifActive.behavior: 'persist'`: Save the signal to memory without adding it to the running loop.
+- `ifActive.behavior: 'discard'`: Ignore the signal while the thread is active.
+- `ifIdle.behavior: 'wake'`: Start a stream with the signal as the first input. This is the default.
+- `ifIdle.behavior: 'persist'`: Save the signal to memory without starting a stream.
+- `ifIdle.behavior: 'discard'`: Ignore the signal while the thread is idle.
+
+Pass `ifIdle.streamOptions` when the idle wake-up stream needs options such as model settings, tools, or runtime context. You do not need to repeat `memory.resource` or `memory.thread`; Mastra uses the top-level `resourceId` and `threadId` for the thread.
+
+```typescript
+agent.sendSignal(
+  {
+    type: 'user-message',
+    contents: 'Continue with the next step.',
+  },
+  {
+    resourceId: 'user_123',
+    threadId: 'thread_456',
+    ifIdle: {
+      behavior: 'wake',
+      streamOptions: {
+        maxSteps: 3,
+      },
+    },
+  },
+)
+```
+
+## Send external event context
+
+Use custom signal types for system-generated context. Non-user signal types are rendered as XML-style user-role context so they can appear inside conversation history without looking like assistant output.
+
+```typescript
+agent.sendSignal(
+  {
+    type: 'system-reminder',
+    contents: 'User X has left a new PR comment asking for a smaller API surface.',
+    attributes: {
+      type: 'github',
+      pr: '123',
+    },
+  },
+  {
+    resourceId: 'user_123',
+    threadId: 'thread_456',
+  },
+)
+```
+
+The model receives the custom signal as context like this:
+
+```xml
+<system-reminder type="github" pr="123">User X has left a new PR comment asking for a smaller API surface.</system-reminder>
+```
+
+Use XML-safe signal type names and attribute names. Signal type names and attribute names can contain letters, numbers, underscores, periods, and hyphens. They must start with a letter or underscore.
+
+## Use the client SDK
+
+The JavaScript client exposes the same thread signal APIs. Use `subscribeToThread()` before `sendSignal()` so the client can render the stream that wakes from, or receives, the signal.
+
+```typescript
+const agent = client.getAgent('supportAgent')
+
+const subscription = await agent.subscribeToThread({
+  resourceId: 'user_123',
+  threadId: 'thread_456',
+})
+
+await agent.sendSignal({
+  signal: {
+    type: 'user-message',
+    contents: 'Show the shorter version.',
+  },
+  resourceId: 'user_123',
+  threadId: 'thread_456',
+})
+
+await subscription.processDataStream({
+  onChunk: chunk => {
+    console.log(chunk)
+  },
+})
+```
+
+## Related
+
+- [`Agent.sendSignal()`](https://mastra.ai/reference/agents/agent)
+- [`Agent.subscribeToThread()`](https://mastra.ai/reference/agents/agent)
+- [`client.getAgent().sendSignal()`](https://mastra.ai/reference/client-js/agents)
+- [`client.getAgent().subscribeToThread()`](https://mastra.ai/reference/client-js/agents)

package/.docs/docs/agents/using-tools.md

@@ -224,6 +224,14 @@ export const weatherTool = createTool({
 })
 ```
 
+## Transform tool payloads for UI and transcripts
+
+Use `transform` when a tool returns raw data your application needs, but browser-facing streams or user-visible transcript messages should receive a smaller or safer shape. `transform` is separate from `toModelOutput`: `toModelOutput` shapes the payload sent back to the model, while `transform` shapes tool input, output, errors, approval payloads, and suspension payloads for `display` and `transcript` targets.
+
+If a transform is configured and it fails, Mastra does not fall back to the raw payload for display or transcript targets. Input deltas are suppressed when no safe `inputDelta` transform is available.
+
+See the [`createTool()` reference](https://mastra.ai/reference/tools/create-tool) for a `transform` example. For shared rules across several tools, configure the agent-level `transform` policy in the [`Agent` constructor](https://mastra.ai/reference/agents/agent).
+
 ## Control tool selection
 
 Pass `toolChoice` or `activeTools` to `.generate()` or `.stream()` to control which tools the agent uses at runtime.

package/.docs/docs/browser/agent-browser.md

@@ -65,6 +65,21 @@ When interacting with pages:
 
 > **Note:** For local launches (the default), AgentBrowser requires a Chromium binary installed via Playwright. This is normally downloaded automatically when you install `@mastra/agent-browser`. If launching the browser fails with `"browser executable is missing"`, run `npx playwright install chromium`. If you connect to a remote browser using the [`cdpUrl`](https://mastra.ai/reference/browser/agent-browser) option, no local Chromium is needed.
 
+## Screenshots
+
+When the agent uses the `browser_screenshot` tool, it captures a PNG image of the current page and returns it as image content that vision-capable models can interpret directly.
+
+Use screenshots when you need to visually inspect the page — for example, evaluating images, layout, or colors. For text or structured data, use `browser_snapshot` instead.
+
+To disable the screenshot tool for models that do not support vision, use `excludeTools`:
+
+```typescript
+const browser = new AgentBrowser({
+  headless: false,
+  excludeTools: ['browser_screenshot'],
+})
+```
+
 ## Element refs
 
 AgentBrowser uses accessibility tree refs to identify elements. When an agent calls `browser_snapshot`, it receives a text representation of the page with refs like `@e1`, `@e2`, etc. The agent then uses these refs with other tools to interact with elements.

package/.docs/docs/browser/stagehand.md

@@ -61,7 +61,8 @@ Use stagehand tools to interact with pages:
 - stagehand_navigate to go to URLs
 - stagehand_act to perform actions described in natural language
 - stagehand_extract to get structured data from the page
-- stagehand_observe to find available actions on the page`,
+- stagehand_observe to find available actions on the page
+- stagehand_screenshot to visually inspect the page`,
 })
 ```
 
@@ -107,6 +108,29 @@ Returns a list of available actions:
 ]
 ```
 
+## Screenshots
+
+When the agent uses the `stagehand_screenshot` tool, it captures a PNG image of the current page and returns it as image content that vision-capable models can interpret directly.
+
+Use screenshots when you need to visually inspect the page — for example, evaluating images, layout, or colors. For text or structured data, use `stagehand_extract` or `stagehand_observe` instead.
+
+```typescript
+const browser = new StagehandBrowser({
+  headless: false,
+  model: 'openai/gpt-5.4',
+})
+```
+
+To disable the screenshot tool for models that do not support vision, use `excludeTools`:
+
+```typescript
+const browser = new StagehandBrowser({
+  headless: false,
+  model: 'openai/gpt-5.4',
+  excludeTools: ['stagehand_screenshot'],
+})
+```
+
 ## Browserbase
 
 Stagehand has native Browserbase integration for cloud browser infrastructure:

package/.docs/docs/deployment/cloud-providers.md

@@ -4,7 +4,7 @@ Mastra applications can be deployed to cloud providers and serverless platforms.
 
 ## Mastra platform
 
-Mastra provides a platform to deploy your server to the cloud. Read the [Mastra platform deployment guide](https://mastra.ai/guides/deployment/mastra-platform) to learn more.
+Mastra provides a platform to deploy your server to the cloud. Read the [Mastra platform deployment guide](https://mastra.ai/docs/mastra-platform/overview) to learn more.
 
 ## Cloud providers
 

package/.docs/docs/deployment/overview.md

@@ -1,6 +1,6 @@
 # Deployment overview
 
-Mastra applications can be deployed to any Node.js-compatible environment. You can deploy a Mastra server, integrate with an existing web framework, deploy to cloud providers, or use [Mastra platform](https://mastra.ai/docs/mastra-platform/overview) for Studio and server deployment.
+Mastra applications can be deployed to any Node.js-compatible environment. You can deploy a Mastra server, integrate with an existing web framework, deploy to cloud providers, or use [Mastra platform](https://mastra.ai/docs/mastra-platform/overview) for observability, Studio, and server deployment.
 
 ## Runtime support
 
@@ -27,12 +27,13 @@ Read about [monorepo deployment](https://mastra.ai/docs/deployment/monorepo).
 
 ### Mastra platform
 
-The [Mastra platform](https://mastra.ai/docs/mastra-platform/overview) provides two products for deploying and managing AI applications built with the Mastra framework:
+The [Mastra platform](https://mastra.ai/docs/mastra-platform/overview) provides three products for deploying, monitoring, and managing AI applications built with the Mastra framework:
 
-- **Studio**: A hosted visual environment for testing agents, running workflows, and inspecting traces
-- **Server**: A production deployment target that runs your Mastra application as an API server
+- [**Observability**](https://mastra.ai/docs/mastra-platform/observability): A standalone hosted product for searchable traces, logs, and metrics across Mastra projects and deploys
+- [**Studio**](https://mastra.ai/docs/mastra-platform/studio): A hosted visual environment for testing agents, running workflows, and inspecting traces
+- [**Server**](https://mastra.ai/docs/mastra-platform/server): A production deployment target that runs your Mastra application as an API server
 
-Learn more in the [Studio deployment guide](https://mastra.ai/docs/studio/deployment) and [Server deployment guide](https://mastra.ai/guides/deployment/mastra-platform).
+Learn more in the [Mastra platform overview](https://mastra.ai/docs/mastra-platform/overview).
 
 ### Cloud Providers
 

package/.docs/docs/editor/tools.md

@@ -73,7 +73,7 @@ Integration providers connect external tool platforms to the editor. Once regist
    })
    ```
 
-   Composio tool slugs use a format like `GITHUB_CREATE_ISSUE`. Tool calls are scoped to a `userId` passed through request context for per-user authentication.
+   Composio tool slugs use a format like `GITHUB_CREATE_ISSUE`. Tool calls are scoped to the `resourceId` passed through request context for per-user authentication.
 
 ### Arcade
 

package/.docs/docs/index.md

@@ -126,8 +126,8 @@ Templates: [Customer Feedback Summarization](https://mastra.ai/templates/custome
 
 Browse [templates](https://mastra.ai/templates) for working examples.
 
-## Not ready to build yet?
+## Want to learn more?
 
-Watch this quick introduction:
+Here's a quick introduction:
 
 [YouTube video player](https://www.youtube-nocookie.com/embed/1qnmnRICX50)

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

@@ -41,18 +41,34 @@ To pin the deploy to a specific env file (instead of relying on the default sele
 mastra studio deploy --env-file .env.production --yes
 ```
 
+### Observability
+
+The following environment variables configure the Observability product on the Mastra platform.
+
+| Variable                                 | Description                                                                                                                                                                                   |
+| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MASTRA_PLATFORM_ACCESS_TOKEN`           | Org-scoped access token. The CLI writes this during observability provisioning and uses it for platform authentication.                                                                       |
+| `MASTRA_PROJECT_ID`                      | UUID of the platform project. `MastraPlatformExporter` uses it to link observability data to the platform project. Studio and Server deploys read the project ID from `.mastra-project.json`. |
+| `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT` | Optional observability endpoint override. This is only set automatically for local platform development. Defaults to `https://observability.mastra.ai`.                                       |
+| `MASTRA_ORG_ID`                          | Overrides the active organization for CLI commands. You can also set it with the `--org` flag on supported commands.                                                                          |
+
+`MastraPlatformExporter` reads `MASTRA_PLATFORM_ACCESS_TOKEN` to authenticate platform export.
+
 ## Multiple environments
 
-A platform project maps to a single deployed instance with one set of env vars. There is no built-in concept of `staging` vs `production` slots within a project. To run the same codebase across multiple environments, create one project per environment and override `.mastra-project.json` per deploy.
+A platform project maps to a single deployed instance with one set of env vars. Platform projects don't have built-in `staging` vs `production` slots. To run the same codebase across multiple environments, create one project per environment and use the matching `.mastra-project.json` file for each deploy.
 
 ```bash
-# Create-and-deploy each environment (first time only)
+# Create and deploy each environment for the first time.
 mastra studio deploy --project "my-app-staging" --env-file .env.staging --yes
 mastra studio deploy --project "my-app-production" --env-file .env.production --yes
 
-# Subsequent deploys — set MASTRA_PROJECT_ID per environment
-MASTRA_PROJECT_ID="<staging-id>" mastra studio deploy --env-file .env.staging --yes
-MASTRA_PROJECT_ID="<production-id>" mastra studio deploy --env-file .env.production --yes
+# For subsequent deploys, restore the matching .mastra-project.json file before deploying.
+cp .mastra-project.staging.json .mastra-project.json
+mastra studio deploy --env-file .env.staging --yes
+
+cp .mastra-project.production.json .mastra-project.json
+mastra studio deploy --env-file .env.production --yes
 ```
 
-Each project has its own Studio URL and its own observability data. When using [`CloudExporter`](https://mastra.ai/docs/observability/tracing/exporters/cloud), set `MASTRA_PROJECT_ID` and `MASTRA_CLOUD_ACCESS_TOKEN` per environment so traces route to the matching Studio project.
+Each project has its own Studio URL and can send observability data to the Mastra platform. When using [`MastraPlatformExporter`](https://mastra.ai/docs/observability/tracing/exporters/mastra-platform), set `MASTRA_PROJECT_ID` and `MASTRA_PLATFORM_ACCESS_TOKEN` per environment so traces route to the matching platform project.