@mastra/mcp-docs-server 1.1.46-alpha.3 → 1.1.46

package/.docs/docs/browser/browser-viewer.md

@@ -1,6 +1,6 @@
 # BrowserViewer
 
-The `@mastra/browser-viewer` package provides browser automation for CLI-based tools like [agent-browser](https://www.npmjs.com/package/agent-browser), [browser-use](https://pypi.org/project/browser-use/), and [browse](https://www.npmjs.com/package/@browserbasehq/browse-cli). BrowserViewer launches Chrome via Playwright, exposes a Chrome DevTools Protocol (CDP) URL, and automatically injects it into CLI commands run through [workspace tools](https://mastra.ai/docs/workspace/overview).
+The `@mastra/browser-viewer` package provides browser automation for CLI-based tools like [agent-browser](https://www.npmjs.com/package/agent-browser), [browser-use](https://pypi.org/project/browser-use/), and [browse](https://www.npmjs.com/package/browse). BrowserViewer launches Chrome via Playwright, exposes a Chrome DevTools Protocol (CDP) URL, and automatically injects it into CLI commands run through [workspace tools](https://mastra.ai/docs/workspace/overview).
 
 ## When to use BrowserViewer
 
@@ -58,6 +58,8 @@ Create a workspace with BrowserViewer and assign it to an agent:
 ```typescript
 import { Mastra } from '@mastra/core/mastra'
 import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
 import { Workspace, LocalSandbox } from '@mastra/core/workspace'
 import { BrowserViewer } from '@mastra/browser-viewer'
 
@@ -77,10 +79,15 @@ const browserAgent = new Agent({
   workspace,
   instructions: `You are a web automation assistant.
 Use browser-use commands to navigate and interact with websites.`,
+  memory: new Memory(),
 })
 
 export const mastra = new Mastra({
   agents: { browserAgent },
+  storage: new LibSQLStore({
+    id: 'mastra-storage',
+    url: 'file:./mastra.db',
+  }),
 })
 ```
 
@@ -97,7 +104,16 @@ When the agent runs a CLI command like `browser-use open https://example.com`, M
 
 BrowserViewer supports three CLI providers. Each CLI must be installed separately in your workspace environment. Each CLI also publishes a [skill](https://mastra.ai/docs/workspace/skills) that teaches the agent its commands and workflows.
 
-### agent-browser
+Set the `cli` option to match the CLI your agent uses:
+
+```typescript
+const viewer = new BrowserViewer({
+  cli: 'browser-use',
+  headless: false,
+})
+```
+
+### `agent-browser`
 
 ```bash
 npm install -g agent-browser
@@ -106,7 +122,7 @@ npx skills add vercel-labs/agent-browser
 
 CDP flag: `--cdp`
 
-### browser-use
+### `browser-use`
 
 ```bash
 pip install browser-use
@@ -115,24 +131,15 @@ npx skills add browser-use/browser-use --skill browser-use
 
 CDP flag: `--cdp-url`
 
-### browse-cli
+### `browse`
 
 ```bash
-npm install -g @browserbasehq/browse-cli
-npx skills add browserbase/skills
+npm install -g browse
+browse skills install
 ```
 
 CDP flag: `--ws`
 
-Set the `cli` option to match the CLI your agent uses:
-
-```typescript
-const viewer = new BrowserViewer({
-  cli: 'browser-use',
-  headless: false,
-})
-```
-
 > **Note:** See [BrowserViewer reference](https://mastra.ai/reference/browser/browser-viewer) for all configuration options, advanced connection modes, and method details.
 
 ## Related

package/.docs/docs/browser/overview.md

@@ -144,7 +144,7 @@ yarn add ws @hono/node-ws
 bun add ws @hono/node-ws
 ```
 
-> **Note:** These packages are not included by default because they are incompatible with serverless environments like Cloudflare Workers. If they are not installed, screencast is disabled but all other browser functionality works normally.
+> **Note:** These packages aren't included by default because they're incompatible with serverless environments like Cloudflare Workers. If they aren't installed, screencast is disabled but all other browser functionality works normally.
 
 Screencast is enabled by default and can be configured:
 

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

@@ -121,7 +121,7 @@ const browser = new StagehandBrowser({
 })
 ```
 
-To disable the screenshot tool for models that do not support vision, use `excludeTools`:
+To disable the screenshot tool for models that don't support vision, use `excludeTools`:
 
 ```typescript
 const browser = new StagehandBrowser({

package/.docs/docs/editor/overview.md

@@ -97,7 +97,7 @@ When `source` is `'code'`, the editor writes each override to a deterministic JS
 
 ### Versioning with the code source
 
-The code source uses the Git history of each per-agent JSON file as its version history. Each commit that changes a file appears as a read-only version in Studio, labeled with the commit message. Saving in Studio updates the working file in place rather than creating a database draft, so the version dropdown reflects your actual commit history.
+The code source uses the Git history of each per-agent JSON file as its version history. Each commit that changes a file is shown as a read-only version in Studio, labeled with the commit message. Saving in Studio updates the working file in place rather than creating a database draft, so the version dropdown reflects your actual commit history.
 
 This means versions and rollbacks are managed through Git rather than through draft and publish actions.
 
@@ -159,11 +159,11 @@ The same operations are available over HTTP through the Mastra server. Use these
 | `GET`    | `/stored/agents/:storedAgentId/dependents` | List agents that reference this agent as a sub-agent.            |
 | `POST`   | `/stored/agents/:storedAgentId/export`     | Export a stored agent's override as a deterministic JSON config. |
 
-The dependents endpoint helps warn before deleting or unsharing an agent that other agents depend on: `dependents` lists caller-readable agents by `id` and `name`, while `hiddenCount` aggregates cross-workspace references the caller cannot read (surfaced only when the target is public). The export endpoint returns only the fields the agent's [`editor` config](https://mastra.ai/reference/agents/agent) allows, so the output matches the per-agent file the code source writes to disk. The Client SDK wraps these endpoints with `client.listStoredAgents()`, `client.createStoredAgent()`, `client.getStoredAgent()`, `client.getStoredAgent(id).dependents()`, and `client.getStoredAgent(id).export()`. Version management endpoints live under `/stored/agents/:storedAgentId/versions`, see [version management](https://mastra.ai/reference/client-js/agents) for the full list.
+The dependents endpoint helps warn before deleting or unsharing an agent that other agents depend on: `dependents` lists caller-readable agents by `id` and `name`, while `hiddenCount` aggregates cross-workspace references the caller can't read (surfaced only when the target is public). The export endpoint returns only the fields the agent's [`editor` config](https://mastra.ai/reference/agents/agent) allows, so the output matches the per-agent file the code source writes to disk. The Client SDK wraps these endpoints with `client.listStoredAgents()`, `client.createStoredAgent()`, `client.getStoredAgent()`, `client.getStoredAgent(id).dependents()`, and `client.getStoredAgent(id).export()`. Version management endpoints live under `/stored/agents/:storedAgentId/versions`, see [version management](https://mastra.ai/reference/client-js/agents) for the full list.
 
 ### Automated experimentation
 
-Because stored agents are just data, you can build automation loops that tune agents without human involvement. A common pattern is to pair the editor API with [datasets](https://mastra.ai/docs/evals/datasets/overview) and [experiments](https://mastra.ai/docs/evals/datasets/running-experiments):
+Because stored agents are data, you can build automation loops that tune agents without human involvement. A common pattern is to pair the editor API with [datasets](https://mastra.ai/docs/evals/datasets/overview) and [experiments](https://mastra.ai/docs/evals/datasets/running-experiments):
 
 - Run a dataset through the current version of an agent and score the results.
 - Have another agent read the failing cases and propose changes to the instructions or tools.
@@ -186,7 +186,7 @@ When you edit a code-defined agent through the editor, only specific fields can
 
 Fields like the agent's `id`, `name`, and `model` come from your code and can't be changed through the editor for code-defined agents. The variables are also read-only.
 
-### Controlling what is editable
+### Controlling what's editable
 
 Use the `editor` field on a code-defined agent to control which fields the editor can override. This lets you keep some fields code-owned while allowing edits to others:
 
@@ -226,7 +226,7 @@ Each version has one of three statuses:
 | --------- | ----------------------------------------------------------------------------------- |
 | Draft     | The latest working copy. Every save creates a new draft version.                    |
 | Published | The active version used in production. Only one version can be published at a time. |
-| Archived  | A previous version that is no longer active. You can restore any archived version.  |
+| Archived  | A previous version that's no longer active. You can restore any archived version.   |
 
 The typical flow is: Edit the draft, test it, then activate it to make it the published version. The previously published version becomes archived so you can restore it if needed. You can do this through Studio or programmatically through the API.
 
@@ -344,7 +344,7 @@ curl -X POST http://localhost:4111/agents/supervisor/generate \
 
 Version overrides propagate automatically through sub-agent delegation via `requestContext`. When a supervisor delegates to a sub-agent, the framework checks if a version override exists for that sub-agent's ID. If one is found, it resolves the stored version from the editor and uses it instead of the code-defined default.
 
-If version resolution fails (for example, when the editor is not configured or the version ID doesn't exist), the framework logs a warning and falls back to the code-defined agent.
+If version resolution fails (for example, when the editor isn't configured or the version ID doesn't exist), the framework logs a warning and falls back to the code-defined agent.
 
 ## Next steps
 

package/.docs/docs/editor/prompts.md

@@ -10,7 +10,7 @@ Prompt blocks are reusable instruction templates that you compose into an agent'
 4. Open an agent's **Instructions** section and select **Add block**.
 5. Pick the saved prompt block from the block picker dialog.
 
-The block appears as a reference in the agent's instruction list. Changes to the original prompt block update every agent that references it.
+The block is added as a reference in the agent's instruction list. Changes to the original prompt block update every agent that references it.
 
 ## Block types
 
@@ -44,7 +44,7 @@ Variables are passed through the agent's `variables` configuration or through [r
 
 Each block can have a **display condition**. A rule group that controls whether the block is included in the final prompt. Conditions are evaluated at runtime against the agent's variables and request context.
 
-A rule group uses **AND** or **OR** logic with one or more conditions. Each condition checks a context field against a value using an operator:
+A rule group uses `AND` or `OR` logic with one or more conditions. Each condition checks a context field against a value using an operator:
 
 | Operator                                       | Description                           |
 | ---------------------------------------------- | ------------------------------------- |
@@ -55,7 +55,7 @@ A rule group uses **AND** or **OR** logic with one or more conditions. Each cond
 | `in` / `not_in`                                | Checks if a value is in an array.     |
 | `exists` / `not_exists`                        | Checks if the field is present.       |
 
-Rule groups can be nested, so you can combine AND and OR conditions for complex logic.
+Rule groups can be nested, so you can combine `AND` and `OR` conditions for complex logic.
 
 In the Studio, open a block's **Display conditions** panel to set up rules visually. You can also configure conditions programmatically through the API. Blocks without conditions are always included.
 

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

@@ -24,7 +24,7 @@ In the Studio, select a tool in the agent's tool list and edit the **Description
 
 Each tool in an agent can have display conditions — rule groups that control whether the tool is available at runtime. This uses the same rule system as [prompt blocks](https://mastra.ai/docs/editor/prompts).
 
-When a request comes in, the editor evaluates each tool's rules against the current context (agent variables and request context). Tools whose conditions are not met are excluded from that run.
+When a request comes in, the editor evaluates each tool's rules against the current context (agent variables and request context). Tools whose conditions aren't met are excluded from that run.
 
 Use display conditions to:
 
@@ -130,7 +130,7 @@ Tools from MCP servers are namespaced as `serverName_toolName` to avoid conflict
 
 ### Conditional activation
 
-MCP client references in an agent can have display conditions, just like [prompt blocks](https://mastra.ai/docs/editor/prompts). This lets you conditionally include MCP tools based on request context or agent variables.
+MCP client references in an agent can have display conditions, like [prompt blocks](https://mastra.ai/docs/editor/prompts). This lets you conditionally include MCP tools based on request context or agent variables.
 
 ## How tools are merged
 

package/.docs/docs/evals/evals-with-memory.md

@@ -10,13 +10,13 @@ This page covers the three working patterns for running Mastra evals against mem
 
 ## When to use which approach
 
-| Goal                                            | Approach                                                                                  |
-| ----------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| One shared conversation across every item       | [`runEvals` with global `targetOptions.memory`](#shared-thread-with-runevals)             |
-| One independent thread per item, simple CI loop | [`runEvals` per item](#per-item-threads-with-runevals)                                    |
-| Per-item threads driven by a stored `Dataset`   | [`dataset.startExperiment` with an inline task](#dataset-experiments-with-an-inline-task) |
+| Goal                                             | Approach                                                                                  |
+| ------------------------------------------------ | ----------------------------------------------------------------------------------------- |
+| One shared conversation across every item        | [`runEvals` with global `targetOptions.memory`](#shared-thread-with-runevals)             |
+| One independent thread per item, focused CI loop | [`runEvals` per item](#per-item-threads-with-runevals)                                    |
+| Per-item threads driven by a stored `Dataset`    | [`dataset.startExperiment` with an inline task](#dataset-experiments-with-an-inline-task) |
 
-Pre-seeding `RequestContext` with `MastraMemory` is **not** a supported way to drive memory into an agent. Thread resolution reads `args.memory.thread` — `RequestContext.MastraMemory` is populated by `prepare-memory-step` after the agent has already resolved its thread.
+Pre-seeding `RequestContext` with `MastraMemory` **isn't** a supported way to drive memory into an agent. Thread resolution reads `args.memory.thread` — `RequestContext.MastraMemory` is populated by `prepare-memory-step` after the agent has already resolved its thread.
 
 ## Shared thread with `runEvals`
 
@@ -43,7 +43,7 @@ const result = await runEvals({
 })
 ```
 
-`targetOptions` is **global per call**. There is no per-item override on `RunEvalsDataItem` today.
+`targetOptions` is **global per call**. No per-item override on `RunEvalsDataItem` is available today.
 
 ## Per-item threads with `runEvals`
 
@@ -86,7 +86,7 @@ const average = scores.reduce((a, b) => a + b, 0) / scores.length
 
 ## Dataset experiments with an inline task
 
-`dataset.startExperiment({ target: agent })` does **not** forward a `memory` option to the agent — only `requestContext`. To run a stored dataset against a memory-enabled agent, use an inline `task` function and stash `{ threadId, resourceId }` in each item's `metadata`. The scorer pipeline still runs as normal.
+`dataset.startExperiment({ target: agent })` **doesn't** forward a `memory` option to the agent — only `requestContext`. To run a stored dataset against a memory-enabled agent, use an inline `task` function and stash `{ threadId, resourceId }` in each item's `metadata`. The scorer pipeline still runs as normal.
 
 ```typescript
 import { randomUUID } from 'node:crypto'

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

@@ -48,7 +48,7 @@ The CLI authenticates with Mastra platform, creates a platform project, writes t
 
 ### Existing non-Mastra projects
 
-If you already have an application, such as a Next.js app, but have not added Mastra yet, run `mastra init` and enable Mastra Observability when prompted:
+If you already have an application, such as a Next.js app, but haven't added Mastra yet, run `mastra init` and enable Mastra Observability when prompted:
 
 **npm**:
 

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

@@ -60,7 +60,7 @@ A deploy transitions through **queued → uploading → building → deploying
 
 ## CI/CD
 
-Automate deployments from GitHub Actions, GitLab CI, or any CI provider. After your first interactive deploy, CI/CD needs just two things: an API token and the `.mastra-project.json` file committed to your repository.
+Automate deployments from GitHub Actions, GitLab CI, or any CI provider. After your first interactive deploy, CI/CD needs two things: an API token and the `.mastra-project.json` file committed to your repository.
 
 ### Create an API token
 

package/.docs/docs/mcp/mcp-apps.md

@@ -83,7 +83,7 @@ calculatorTool._meta = {
 
 ## Connecting MCP Apps to agents
 
-Agents consume tools — they do not need to know about MCP servers. Pass tools to the agent's `tools` config, and register the MCP server at the Mastra level so Studio can resolve app resources.
+Agents consume tools — they don't need to know about MCP servers. Pass tools to the agent's `tools` config, and register the MCP server at the Mastra level so Studio can resolve app resources.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -158,8 +158,8 @@ Agent calls tool → Tool returns brief content + structuredContent
 
 Tools with app resources should return two fields:
 
-- `content`: A brief text summary for the model. Keep this short so the agent does not parrot the full result.
-- `structuredContent`: The data payload that hydrates the UI. The model does not see this field.
+- `content`: A brief text summary for the model. Keep this short so the agent doesn't parrot the full result.
+- `structuredContent`: The data payload that hydrates the UI. The model doesn't see this field.
 
 ```typescript
 execute: async ({ num1, num2, operation }) => {
@@ -294,7 +294,7 @@ App iframes are sandboxed with the following permissions:
 - `allow-forms`: Allows form submission
 - `allow-popups`: Permits `window.open()` and link targets
 
-The iframe does not have access to the parent page's DOM, cookies, or storage. All communication happens through the JSON-RPC postMessage protocol managed by `@mcp-ui/client`'s `AppRenderer` on the host side and `@modelcontextprotocol/ext-apps`'s `App` class on the guest side.
+The iframe doesn't have access to the parent page's DOM, cookies, or storage. All communication happens through the JSON-RPC postMessage protocol managed by `@mcp-ui/client`'s `AppRenderer` on the host side and `@modelcontextprotocol/ext-apps`'s `App` class on the guest side.
 
 ## Related
 

package/.docs/docs/memory/observational-memory.md

@@ -134,7 +134,7 @@ const memory = new Memory({
 })
 ```
 
-`bufferOnIdle` is off by default. It is separate from `bufferTokens`: `bufferTokens` controls step-time async buffering, while `bufferOnIdle` controls end-of-turn buffering for idle turns.
+`bufferOnIdle` is off by default. It's separate from `bufferTokens`: `bufferTokens` controls step-time async buffering, while `bufferOnIdle` controls end-of-turn buffering for idle turns.
 
 See [the API reference](https://mastra.ai/reference/memory/observational-memory) for the full configuration shape.
 

package/.docs/docs/memory/working-memory.md

@@ -413,12 +413,12 @@ const memory = new Memory({
 What changes:
 
 - **Storage is identical.** The same resource/thread `workingMemory` field is read and written.
-- **The tool is the same shape, exposed under a new name.** Writes still flow through the same underlying tool; on this path it is registered as `setWorkingMemory` (instead of `updateWorkingMemory`). The rename keeps legacy strip filters from removing tool-call parts so they persist as a normal audit trail and the next model step picks the new value up automatically.
+- **The tool is the same shape, exposed under a new name.** Writes still flow through the same underlying tool; on this path it's registered as `setWorkingMemory` (instead of `updateWorkingMemory`). The rename keeps legacy strip filters from removing tool-call parts so they persist as a normal audit trail and the next model step picks the new value up automatically.
 - **Delivery only.** Instead of folding into the system prompt, `Memory` auto-attaches a `WorkingMemoryStateProcessor` that emits the current working memory as a `state` signal with `stateId: 'working-memory'`.
 
 You inherit the standard state-signal benefits: thread-scoped tracking metadata, `cacheKey` dedup so identical snapshots are only emitted once, and `contextWindow.hasSnapshot` re-injection when an older snapshot rolls out of the window.
 
-The default (`useStateSignals: false`) keeps the existing system-message behavior unchanged. `useStateSignals` is not supported with template working memory `version: 'vnext'`.
+The default (`useStateSignals: false`) keeps the existing system-message behavior unchanged. `useStateSignals` isn't supported with template working memory `version: 'vnext'`.
 
 ## Examples
 

package/.docs/docs/observability/integrations/bridges/datadog.md

@@ -148,7 +148,7 @@ new DatadogBridge({
 })
 ```
 
-> **Note:** For most bridge users, agent mode is the right choice. APM data cannot be sent in agentless mode, so enabling agentless splits LLM Observability traffic away from APM traffic. If you want LLM Observability only without an agent, use the [Datadog Exporter](https://mastra.ai/docs/observability/integrations/exporters/datadog) instead.
+> **Note:** For most bridge users, agent mode is the right choice. APM data can't be sent in agentless mode, so enabling agentless splits LLM Observability traffic away from APM traffic. If you want LLM Observability only without an agent, use the [Datadog Exporter](https://mastra.ai/docs/observability/integrations/exporters/datadog) instead.
 
 ## Trace hierarchy
 

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

@@ -153,7 +153,7 @@ const sdk = new NodeSDK({
 
 Logs that originate inside a Mastra span are emitted under that span's OTEL context, so backends like Datadog, Grafana, and Honeycomb correlate them with the surrounding trace automatically. Logs without trace context fall through to the currently active OTEL context.
 
-If you do not register a `LoggerProvider`, log emission is a silent no-op — traces continue to work as configured.
+If you don't register a `LoggerProvider`, log emission is a silent no-op — traces continue to work as configured.
 
 ### Running Your Application
 

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

@@ -100,7 +100,7 @@ export const mastra = new Mastra({
 
 > **Note:** For advanced usage, including the full `MastraExporter` options and multi-agent trace examples, see [Laminar's Mastra integration guide](https://laminar.sh/docs/tracing/integrations/mastra).
 
-Mastra also ships a standalone [`LaminarExporter`](https://mastra.ai/reference/observability/tracing/exporters/laminar) in `@mastra/laminar` that sends spans over OTLP/HTTP. It cannot inherit an active OTel context and does not fully map Mastra spans to Laminar's native format, so use the `@lmnr-ai/lmnr` integration above for `observe()` wrappers, multi-agent root spans, and accurate Laminar rendering.
+Mastra also ships a standalone [`LaminarExporter`](https://mastra.ai/reference/observability/tracing/exporters/laminar) in `@mastra/laminar` that sends spans over OTLP/HTTP. It can't inherit an active OTel context and doesn't fully map Mastra spans to Laminar's native format, so use the `@lmnr-ai/lmnr` integration above for `observe()` wrappers, multi-agent root spans, and accurate Laminar rendering.
 
 ## Related
 

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

@@ -189,10 +189,35 @@ To scope an evaluator to a specific agent, configure either filter in Langfuse:
 - **Trace name**: equals the agent name (for example, `weather-agent`).
 - **Metadata**: `agentId` equals the agent id.
 
-The trace name dropdown in Langfuse evaluator filters lists every distinct value seen, so each agent appears as its own entry once it has produced at least one trace.
+The trace name dropdown in Langfuse evaluator filters lists every distinct value seen, so each agent is shown as its own entry once it has produced at least one trace.
 
 If you set a custom `traceName` via `mastra.metadata.traceName`, your value takes precedence over the default agent name.
 
+## Custom trace metadata
+
+Langfuse filters and groups traces by top-level metadata only. Nested metadata keys can't be used for filtering or grouping.
+
+To add your own top-level metadata, set keys under `langfuse` in your span metadata. The exporter forwards each key to `langfuse.trace.metadata.<key>`, where it becomes filterable in Langfuse:
+
+```typescript
+const tracingOptions = {
+  metadata: {
+    langfuse: {
+      customerId: 'cust_123',
+      tier: 'enterprise',
+    },
+  },
+}
+```
+
+This example produces `langfuse.trace.metadata.customerId` and `langfuse.trace.metadata.tier`.
+
+Notes:
+
+- The reserved `prompt` key is used for [prompt linking](#prompt-linking) and isn't forwarded as trace metadata.
+- The reserved identity keys `agentId`, `agentName`, `workflowId`, and `workflowName` are set from the root span and take precedence over custom values with the same name.
+- Values are sent as strings, because Langfuse maps trace metadata attributes as strings. Numbers, booleans, and objects are serialized with JSON. Langfuse Cloud restores them to their original types on ingestion.
+
 ## Prompt linking
 
 You can link LLM generations to prompts stored in [Langfuse Prompt Management](https://langfuse.com/docs/prompt-management). This enables version tracking and metrics for your prompts.

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

@@ -2,7 +2,7 @@
 
 The `MastraPlatformExporter` sends traces, logs, metrics, scores, and feedback to the Mastra platform. Use it to route observability data from any Mastra app to a hosted project in the Mastra platform.
 
-> **Note:** `MastraPlatformExporter` was previously called `CloudExporter`. The original `CloudExporter` class is still exported from `@mastra/observability` for backward compatibility, but it is deprecated. New code should use `MastraPlatformExporter`.
+> **Note:** `MastraPlatformExporter` was previously called `CloudExporter`. The original `CloudExporter` class is still exported from `@mastra/observability` for backward compatibility, but it's deprecated. New code should use `MastraPlatformExporter`.
 
 > **Self-hosted or standalone apps:** If you host your Mastra application on your own infrastructure (not on Mastra platform), you still need a deployed Studio project to view traces, logs, and metrics. `MastraPlatformExporter` sends data to a Studio project, so one must exist before you can use it.
 >

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

@@ -2,7 +2,7 @@
 
 The `MastraStorageExporter` persists traces to your configured storage backend, making them accessible through Studio. It requires no external services.
 
-> **Note:** `MastraStorageExporter` was previously called `DefaultExporter`. The original `DefaultExporter` class is still exported from `@mastra/observability` for backward compatibility, but it is deprecated. New code should use `MastraStorageExporter`.
+> **Note:** `MastraStorageExporter` was previously called `DefaultExporter`. The original `DefaultExporter` class is still exported from `@mastra/observability` for backward compatibility, but it's deprecated. New code should use `MastraStorageExporter`.
 
 > **Production Observability:** Observability data can quickly overwhelm general-purpose databases in production. For high-traffic applications, route the observability storage domain to [ClickHouse](https://mastra.ai/reference/storage/clickhouse) through [composite storage](https://mastra.ai/reference/storage/composite). See [Production Recommendations](#production-recommendations) for details.
 
@@ -178,11 +178,11 @@ The MastraStorageExporter includes robust error handling for production use:
 
 ## Dropped observability events
 
-`DefaultExporter` emits structured drop events when it cannot persist observability data. Register an exporter or bridge with `onDroppedEvent` to forward these drops to alerting or monitoring.
+`DefaultExporter` emits structured drop events when it can't persist observability data. Register an exporter or bridge with `onDroppedEvent` to forward these drops to alerting or monitoring.
 
-There are two drop reasons:
+For two reasons events are dropped:
 
-- `unsupported-storage`: The storage provider does not implement the signal type.
+- `unsupported-storage`: The storage provider doesn't implement the signal type.
 - `retry-exhausted`: The exporter retried a batch up to `maxRetries` times and then dropped it.
 
 The following example demonstrates forwarding drop details to a monitoring endpoint:

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

@@ -458,7 +458,7 @@ bun add @opentelemetry/exporter-logs-otlp-proto
 bun add @opentelemetry/exporter-logs-otlp-grpc @grpc/grpc-js
 ```
 
-If the matching log exporter package is not installed, log export is silently disabled and traces continue to work.
+If the matching log exporter package isn't installed, log export is silently disabled and traces continue to work.
 
 ## Configuration options
 

package/.docs/docs/observability/integrations/overview.md

@@ -1,6 +1,6 @@
 # Integrations overview
 
-Mastra observability integrations control where observability data goes and how it is transformed on the way out. Use integrations to store data in Mastra storage, send it to Mastra platform, connect to external observability providers, or redact exported span data.
+Mastra observability integrations control where observability data goes and how it's transformed on the way out. Use integrations to store data in Mastra storage, send it to Mastra platform, connect to external observability providers, or redact exported span data.
 
 ## When to use integrations
 

package/.docs/docs/observability/logging.md

@@ -24,7 +24,7 @@ export const mastra = new Mastra({
 
 ## Logging to observability storage
 
-When [observability](https://mastra.ai/docs/observability/overview) is configured, all logger calls are automatically forwarded to your observability storage. This means every `debug`, `info`, `warn`, `error`, and `trackException` call from your application and from Mastra's internal components appears alongside your traces.
+When [observability](https://mastra.ai/docs/observability/overview) is configured, all logger calls are automatically forwarded to your observability storage. This means every `debug`, `info`, `warn`, `error`, and `trackException` call from your application and from Mastra's internal components is stored alongside your traces.
 
 No code changes are required. Mastra wraps the configured logger so that it writes to both the original logger (console, file, or custom transport) and the observability system simultaneously.
 

package/.docs/docs/observability/metrics/overview.md

@@ -8,11 +8,11 @@ Three categories of metrics are emitted automatically:
 - **Token usage metrics**: Input and output token counts broken down by type (text, cache, audio, image, reasoning).
 - **Cost estimation**: Estimated cost per model call based on an embedded pricing registry.
 
-> **Note:** Metrics require an OLAP-capable store for observability. Relational databases like PostgreSQL, LibSQL, etc. are not supported for metrics. In-memory storage resets on restart.
+> **Note:** Metrics require an OLAP-capable store for observability. Relational databases like PostgreSQL, LibSQL, etc. aren't supported for metrics. In-memory storage resets on restart.
 >
 > For local development, use [DuckDB](https://duckdb.org/) through `@mastra/duckdb`. For production, use [ClickHouse](https://clickhouse.com/) through `@mastra/clickhouse`.
 >
-> Google Cloud Spanner supports metrics, but it is not recommended for heavy metrics workloads. The Spanner adapter disables metrics by default because metrics are write-heavy and scan-heavy. Set `disableMetrics: false` only for light workloads, or route metrics to an OLAP store.
+> Google Cloud Spanner supports metrics, but it's not recommended for heavy metrics workloads. The Spanner adapter disables metrics by default because metrics are write-heavy and scan-heavy. Set `disableMetrics: false` only for light workloads, or route metrics to an OLAP store.
 
 ## When to use metrics
 
@@ -83,7 +83,7 @@ export const mastra = new Mastra({
 
 ## Studio
 
-The Studio metrics dashboard visualizes all automatic metrics with KPI cards, detailed breakdowns, and configurable time ranges. See [Studio observability](https://mastra.ai/docs/studio/observability) for a full walkthrough.
+The Studio metrics dashboard visualizes all automatic metrics with KPI cards, detailed breakdowns, token usage timelines, and configurable time ranges. See [Studio observability](https://mastra.ai/docs/studio/observability) for a full walkthrough.
 
 ## What Mastra measures
 

package/.docs/docs/observability/metrics/querying.md

@@ -11,7 +11,7 @@ Mastra exposes the same five OLAP queries (`getMetricAggregate`, `getMetricBreak
 
 For setup of the observability store itself, see the [Metrics overview](https://mastra.ai/docs/observability/metrics/overview). For the list of metric names you can query, see the [Automatic metrics reference](https://mastra.ai/reference/observability/metrics/automatic-metrics).
 
-> **Note:** Metric queries are served by the observability domain, which requires an OLAP-capable store (DuckDB locally, ClickHouse in production). See [Metrics overview](https://mastra.ai/docs/observability/metrics/overview) for setup. If the observability store is not configured, `getStore('observability')` returns `null`.
+> **Note:** Metric queries are served by the observability domain, which requires an OLAP-capable store (DuckDB locally, ClickHouse in production). See [Metrics overview](https://mastra.ai/docs/observability/metrics/overview) for setup. If the observability store isn't configured, `getStore('observability')` returns `null`.
 
 ## Surfaces
 
@@ -46,7 +46,7 @@ export const agentLatencyTool = createTool({
 })
 ```
 
-`getStore('observability')` returns `null` when the configured backend does not support OLAP queries.
+`getStore('observability')` returns `null` when the configured backend doesn't support OLAP queries.
 
 ### HTTP
 

package/.docs/docs/observability/storage.md

@@ -49,7 +49,7 @@ Mastra storage-backed observability currently depends on an OLAP-capable backend
 - ClickHouse: Recommended for production observability.
 - Mastra platform: Use `MastraPlatformExporter` if you want hosted observability without managing the backend yourself.
 
-Primary application stores such as LibSQL or PostgreSQL should not be used as the observability store. Route the `observability` domain separately with composite storage when you use `MastraStorageExporter`.
+Primary application stores such as LibSQL or PostgreSQL shouldn't be used as the observability store. Route the `observability` domain separately with composite storage when you use `MastraStorageExporter`.
 
 ## Local development
 
@@ -67,7 +67,7 @@ Observability traffic is usually more write-heavy than the rest of the applicati
 
 - Use `MastraStorageExporter` with ClickHouse for the `observability` domain when you keep observability in your own storage.
 - Use `MastraPlatformExporter` if you want hosted Mastra platform observability instead of managing the backend yourself.
-- Do not route observability to your primary application store.
+- Don't route observability to your primary application store.
 
 For backend compatibility details and exporter batching behavior, see [Mastra Storage exporter](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage).
 

package/.docs/docs/observability/tracing/overview.md

@@ -133,7 +133,7 @@ export const mastra = new Mastra({
 })
 ```
 
-If `environment` is not set, Mastra falls back to `process.env.NODE_ENV`. If neither is set, the field is left undefined rather than guessed.
+If `environment` isn't set, Mastra falls back to `process.env.NODE_ENV`. If neither is set, the field is left undefined rather than guessed.
 
 Per-call `tracingOptions.metadata.environment` always takes precedence, so individual calls can override the value when needed.
 

package/.docs/docs/server/auth/fga.md

@@ -53,7 +53,7 @@ When using `MastraFGAWorkos`, set `fetchMemberships: true` on `MastraAuthWorkos`
 
 Use `thread` as the resource-mapping key for memory authorization. `MastraFGAWorkos` still accepts the legacy alias `memory`, but new configs should prefer `thread`.
 
-When `server.fga` is configured, Mastra enforces FGA on protected actions. If a protected action has no authenticated user, Mastra denies it. If `server.fga` is not configured, these FGA checks are skipped and Mastra keeps the previous behavior.
+When `server.fga` is configured, Mastra enforces FGA on protected actions. If a protected action has no authenticated user, Mastra denies it. If `server.fga` isn't configured, these FGA checks are skipped and Mastra keeps the previous behavior.
 
 ### Resource mapping
 
@@ -100,7 +100,7 @@ Use `validatePermissions()` to validate the full set of permissions Mastra may e
 
 ### Stored resource scoping
 
-FGA authorizes access to a resource. It does not automatically filter stored records that live in shared storage. Enable stored resource scoping when the built-in stored resource APIs are used in a multi-tenant app.
+FGA authorizes access to a resource. It doesn't automatically filter stored records that live in shared storage. Enable stored resource scoping when the built-in stored resource APIs are used in a multi-tenant app.
 
 ```typescript
 const mastra = new Mastra({
@@ -136,7 +136,7 @@ If `requireScope` is `true` or omitted, scoped stored resource routes fail when
 
 Mastra includes route-level FGA metadata for built-in resource routes, including agents, workflows, tools, MCP tools, memory threads, responses, conversations, and stored resources. Stored resource route coverage includes `/stored/agents`, `/stored/mcp-clients`, `/stored/prompt-blocks`, `/stored/scorers`, `/stored/skills`, and `/stored/workspaces`. A route is checked when it has route-level `fga` metadata, when Mastra can derive built-in metadata for that route, or when the provider supplies metadata with `resolveRouteFGA()`.
 
-To deny protected routes that do not resolve FGA metadata, configure route policy coverage on the FGA provider:
+To deny protected routes that don't resolve FGA metadata, configure route policy coverage on the FGA provider:
 
 ```typescript
 const fga = new MastraFGAWorkos({
@@ -202,20 +202,20 @@ const fga = new MastraFGAWorkos({
 
 When an FGA provider is configured, Mastra automatically checks authorization at these lifecycle points:
 
-| Lifecycle point                                                  | Permission checked                              | Resource type        | Resource ID                                                         |
-| ---------------------------------------------------------------- | ----------------------------------------------- | -------------------- | ------------------------------------------------------------------- |
-| Agent execution (`generate`, `stream`)                           | `agents:execute`                                | `agent`              | `agentId`                                                           |
-| Built-in workflow HTTP execution routes and `Workflow.execute()` | `workflows:execute`                             | `workflow`           | `workflowId`                                                        |
-| Standalone tool execution                                        | `tools:execute`                                 | `tool`               | `toolName`                                                          |
-| Agent tool execution                                             | `tools:execute`                                 | `tool`               | `${agentId}:${toolName}`                                            |
-| MCP tool execution                                               | `tools:execute`                                 | `tool`               | `JSON.stringify([serverName, toolName])`                            |
-| Thread and memory access                                         | `memory:read`, `memory:write`, `memory:delete`  | `thread`             | `threadId`                                                          |
-| Stored resource routes                                           | Stored resource permission for the route action | Stored resource type | Route record ID, or the stored-resource scope for collection routes |
-| HTTP resource routes                                             | Configured per route                            | Configured per route | Configured per route                                                |
+| Lifecycle point                                                  | Permission checked                              | Resource type                                                         | Resource ID                                                                         |
+| ---------------------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Agent execution (`generate`, `stream`)                           | `agents:execute`                                | `agent`                                                               | `agentId`                                                                           |
+| Built-in workflow HTTP execution routes and `Workflow.execute()` | `workflows:execute`                             | `workflow`                                                            | `workflowId`                                                                        |
+| Standalone tool execution                                        | `tools:execute`                                 | `tool`                                                                | `toolName`                                                                          |
+| Agent tool execution                                             | `tools:execute`                                 | `tool`                                                                | `${agentId}:${toolName}`                                                            |
+| MCP tool execution                                               | `tools:execute`                                 | `tool` by default, or the server-level `fga.resourceMapping` override | `JSON.stringify([serverName, toolName])` by default, or the server-level derived ID |
+| Thread and memory access                                         | `memory:read`, `memory:write`, `memory:delete`  | `thread`                                                              | `threadId`                                                                          |
+| Stored resource routes                                           | Stored resource permission for the route action | Stored resource type                                                  | Route record ID, or the stored-resource scope for collection routes                 |
+| HTTP resource routes                                             | Configured per route                            | Configured per route                                                  | Configured per route                                                                |
 
-For OAuth-protected MCP servers, HTTP MCP transports pass authenticated data as `extra.authInfo`. If an `MCPServer` is registered on an FGA-enabled Mastra instance, configure `mapAuthInfoToUser` so Mastra can set `requestContext.get('user')` before checking `tools/list` and `tools/call`. See [MCPServer authentication context](https://mastra.ai/reference/tools/mcp-server).
+For OAuth-protected MCP servers, HTTP MCP transports pass authenticated data as `extra.authInfo`. If an `MCPServer` is registered on an FGA-enabled Mastra instance, configure `mapAuthInfoToUser` so Mastra can set `requestContext.get('user')` before checking `tools/list` and `tools/call`. Use the server-level `fga` option when MCP tool checks need different resource or permission mapping than internal agent and workflow tool checks. See [MCPServer authentication context](https://mastra.ai/reference/tools/mcp-server).
 
-Direct SDK calls to `createRun().start()`, `resume()`, or `restart()` are not independently checked by core FGA in this release. Make those calls from a protected route or guard them in application code. Pass a `requestContext` with an authenticated user when invoking protected entry points directly.
+Direct SDK calls to `createRun().start()`, `resume()`, or `restart()` aren't independently checked by core FGA in this release. Make those calls from a protected route or guard them in application code. Pass a `requestContext` with an authenticated user when invoking protected entry points directly.
 
 Core agent, internal workflow, tool, and memory checks also pass `requestContext` and action metadata to the FGA provider. Route checks pass `requestContext`. Thread checks pass the owning `resourceId` when available.