@mastra/mcp-docs-server 1.2.23-alpha.6 → 1.2.23-alpha.9

package/.docs/docs/harness/durable-agents.md

@@ -70,7 +70,7 @@ A durable agent adds three layers on top of a regular agent:
 
 1. **Workflow execution**: `stream()` serializes the messages and options into a workflow input, then triggers the agentic loop inside a durable workflow. The workflow runs the same loop as `Agent.stream()` but each step can be memoized and replayed.
 
-2. **PubSub streaming**: As the loop runs, chunks are published to a PubSub topic keyed by the run ID. The caller subscribes to this topic and pipes chunks into a `ReadableStream`. If the caller disconnects and reconnects, missed chunks are replayed from the cache.
+2. **PubSub streaming**: The loop publishes chunks to a PubSub topic keyed by the run ID. The caller subscribes to that topic and pipes the chunks into a `ReadableStream`, while the cache replays any chunks missed during a disconnect.
 
 3. **Cache layer**: An optional cache (in-memory by default, Redis or another backend in production) stores published events so that a late subscriber can catch up.
 

package/.docs/docs/harness/schedules.md

@@ -8,7 +8,7 @@
 
 > **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/harness/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.
+A schedule runs an agent on a cron cadence. On each fire, Mastra sends a prompt either as a [signal](https://mastra.ai/docs/harness/signals) into a thread or as a threadless [`agent.generate()`](https://mastra.ai/reference/agents/generate) run. Use schedules for recurring work such as daily summaries and periodic checks, including scheduled nudges into a conversation.
 
 Schedules are persisted, so they survive restarts and redeploys. Manage them at runtime through [`mastra.schedules`](https://mastra.ai/reference/schedules/overview), the canonical create, read, update, and delete (CRUD) surface. The same surface also manages [workflow schedules](https://mastra.ai/docs/workflows/scheduled-workflows) (pass `workflowId` instead of `agentId` to schedule a workflow).
 

package/.docs/docs/harness/signal-providers.md

@@ -130,7 +130,7 @@ Mastra calls `poll()` on the `pollInterval` with all active subscriptions. It sk
 
 Use polling when the external source doesn't push events to your app. Set `pollInterval` and override `poll(subscriptions)`. Each subscription includes the thread target and the external resource id to inspect.
 
-Use webhooks when the external source can call your app. Override `handleWebhook(request)`, parse the payload, find matching subscriptions, and call `notify()` for each match.
+Use webhooks when the external source can call your app. Override `handleWebhook(request)` to parse the payload, then find matching subscriptions and call `notify()` for every match.
 
 ```typescript
 import { SignalProvider } from '@mastra/core/signals'

package/.docs/docs/harness/signals.md

@@ -8,7 +8,7 @@
 
 > **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.
+Signals let you 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 wakes an idle agent or delivers input to its running loop; alternatively, it queues the input for the next turn.
 
 Use message APIs for user-authored input. Use `sendSignal()` for lower-level system context, such as background task notifications, policy reminders, or processor-generated context.
 

package/.docs/docs/index.md

@@ -239,7 +239,7 @@ Templates: [GitHub PR Code Review](https://mastra.ai/templates/github-pr-code-re
 <details>
 **Sales and go-to-market workflows**
 
-Turn customer conversations into structured tasks, generate investment memos, or automate outreach sequences.
+Turn customer conversations into structured tasks or generate investment memos. You can also automate outreach sequences.
 
 Used by [Kestral](https://mastra.ai/blog/kestral), [Orange Collective](https://mastra.ai/blog/orange-collective-vc-operating-system), [WorkOS](https://mastra.ai/blog/workos-teaching-mastra)
 

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

@@ -42,17 +42,17 @@ A local `.env` file is optional. Environment variables stored on the platform ar
    Preflight needs TURSO_DATABASE_URL for the production environment. Create a managed turso database now and attach it? (Y/n)
    ```
 
-   Accept the prompt and provisioning takes a few seconds — the database's connection variables are injected into your deploys automatically, with nothing to copy into an `.env` file. Decline it, or run in a non-interactive shell (CI, `--yes`), and the CLI falls back to the previous behavior: it prints the exact command to run yourself.
+   Accept the prompt, and provisioning takes a few seconds. The database's connection variables are injected into your deploys automatically, so you don't need to copy them into an `.env` file. If you decline the prompt or use a non-interactive shell (CI, `--yes`), the CLI falls back to printing the exact command for you to run.
 
    ```bash
    mastra env db create production --kind turso
    ```
 
-   The environment slug (`production` above) matches the environment the CLI would have deployed to — this is important because `mastra env db create` requires an environment argument in non-interactive shells when the project has more than one environment.
+   The environment slug (`production` above) matches the environment the CLI would have deployed to. The `mastra env db create` command requires an environment argument in non-interactive shells when the project has more than one environment.
 
-   Preflight also catches database URLs that point at your local machine. A `.env` file with `REDIS_URL=redis://localhost:6379` works during development, but the deployed server can't reach your laptop — so the CLI warns and offers the same managed provisioning. If you decline, the deploy continues with your value as-is; if you accept, the managed database's connection variables take precedence at deploy time while your local `.env` keeps working for development.
+   Preflight also catches database URLs that point at your local machine. A `.env` file with `REDIS_URL=redis://localhost:6379` works during development, but the deployed server can't reach your laptop. The CLI therefore warns and offers the same managed provisioning. If you decline, the deploy continues with your value as-is; if you accept, the managed database's connection variables take precedence at deploy time while your local `.env` keeps working for development.
 
-   > **Note:** If preflight reports a hard-coded local path instead (`Build contains a host-local storage URL`), it can't offer the inline fix — guard the path with an environment variable first so the file is only used during local development:
+   > **Note:** If preflight reports a hard-coded local path instead (`Build contains a host-local storage URL`), it can't offer the inline fix. Guard the path with an environment variable first so the file is only used during local development:
    >
    > ```ts
    > new LibSQLStore({
@@ -69,7 +69,7 @@ A local `.env` file is optional. Environment variables stored on the platform ar
 
    > **Warning:** Set up [authentication](https://mastra.ai/docs/auth/overview) before exposing your endpoints publicly.
 
-Each deploy replaces the running server process, which affects agent turns that are still streaming when the new version goes live. Because Mastra Platform doesn't currently provide a configurable or guaranteed termination grace period, don't rely on a raised `server.drainTimeout` for turns that may run longer than the default drain window. Use [durable agents](https://mastra.ai/docs/harness/durable-agents) with persistent storage and cache when turns must survive a deploy, or handle an interrupted stream in the client. See [graceful shutdown and rolling deploys](https://mastra.ai/docs/deployment/mastra-server) for the available strategies.
+Replacing the running server process during each deploy can interrupt agent turns that are still streaming when the new version goes live because Mastra Platform doesn't currently let you configure or rely on guaranteed extra time before termination. Don't rely on a raised `server.drainTimeout` for turns that may outlast the default drain window. Use [durable agents](https://mastra.ai/docs/harness/durable-agents) with persistent storage and cache when turns must survive a deploy, or handle an interrupted stream in the client. The available strategies are documented in [graceful shutdown and rolling deploys](https://mastra.ai/docs/deployment/mastra-server).
 
 The first deploy writes a `.mastra-project.json` file linking your directory to the platform project. Commit it so later deploys, CI runs, and [`mastra env`](https://mastra.ai/docs/mastra-platform/environments) commands target the same project without extra flags.
 
@@ -93,7 +93,7 @@ Pass `--region` when a deploy creates a new environment to control where it runs
 mastra deploy --env production --region eu
 ```
 
-The region is fixed when the environment is created. Databases attached to an environment are placed near that environment's region automatically, and observability data is routed to the ingest region that matches the environment's residency zone. See [Regions](https://mastra.ai/docs/mastra-platform/regions) for the full list of supported regions, database placement, and observability co-location.
+The region is fixed when the environment is created. Databases attached to an environment are placed near that environment's region automatically, and observability data is routed to the ingest region that matches the environment's residency zone. See [Regions](https://mastra.ai/docs/mastra-platform/regions) for the full list of supported regions and database placement, along with observability co-location.
 
 ## Preflight checks
 
@@ -151,7 +151,7 @@ Projects that depend on packages from a private registry install them during the
    //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.
+   Keep the `${NPM_TOKEN}` reference literal. The package manager resolves it at install time, so the token itself is never written to your repository.
 
 3. Deploy as usual:
 
@@ -229,14 +229,14 @@ The deploy log is the source of truth: the legacy pipeline prints a deprecation
    Check whether this project is ready for the Mastra Platform environment pipeline.
 
    1. Find the installed version of `@mastra/core` (check package.json and the
-      lockfile for the version that actually resolved, not just the range).
-   2. If it is >= 1.44.0, tell me I'm good — no further action needed.
-   3. If it is < 1.44.0:
+      lockfile for the version that actually resolved, rather than only the range).
+   2. If it's >= 1.44.0, tell me I'm good. No further action is needed.
+   3. If it's < 1.44.0:
       a. Fetch the `@mastra/core` changelog from
          https://github.com/mastra-ai/mastra/blob/main/packages/core/CHANGELOG.md
          and read every entry between my installed version and the latest release.
       b. Scan my project (agents, workflows, tools, memory, storage, deployers,
-         telemetry — anywhere `@mastra/core`, `@mastra/*`, or `mastra` is imported)
+         telemetry, anywhere `@mastra/core`, `@mastra/*`, or `mastra` is imported)
          and list every Mastra API surface I actually use.
       c. For each used API, cross-reference the changelog and produce a table of:
          API I use → breaking change → severity (breaks build / breaks runtime /
@@ -248,11 +248,11 @@ The deploy log is the source of truth: the legacy pipeline prints a deprecation
          versions, then run typecheck and tests. Report anything still failing.
    4. Search my scripts, package.json, Dockerfiles, and CI config for
       `mastra server deploy` and `mastra studio deploy`. Replace each
-      occurrence with `mastra deploy` — this is the unified command required
+      occurrence with `mastra deploy`. This is the unified command required
       by the environment pipeline.
 
-   Do not restructure my CI, provision new infra, or change my environment
-   variable values — only the Mastra usage in my code and the deploy command
+   don't restructure my CI, provision new infra, or change my environment
+   variable values. Change only the Mastra usage in my code and the deploy command
    itself.
    ```
 
@@ -264,7 +264,7 @@ The deploy log is the source of truth: the legacy pipeline prints a deprecation
    + mastra deploy
    ```
 
-   `mastra deploy` builds once and deploys both the server and the Studio UI shell for the target environment. Any recent `mastra` CLI supports it. If yours doesn't, upgrade with `npm install -g mastra@latest`.
+   `mastra deploy` builds once and deploys both the server and the Studio UI shell for the target environment. It's supported by every recent `mastra` CLI; otherwise, upgrade with `npm install -g mastra@latest`.
 
 3. Deploy once. Your project is auto-adopted onto the environment pipeline and the `production` environment is created on first deploy. See [Environments](https://mastra.ai/docs/mastra-platform/environments) for the full model.
 

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

@@ -32,7 +32,7 @@ mastra deploy --env staging
 mastra env create eu-preview --type preview --region eu
 ```
 
-Each project has a single `production` environment, created by your first deploy. The region is fixed at creation. Databases attached to an environment are placed near the environment's region automatically, and observability data is routed to the ingest region for the matching residency zone. See [Regions](https://mastra.ai/docs/mastra-platform/regions) for the supported regions, database placement, and observability co-location. The number of environments per project depends on your plan.
+Each project has a single `production` environment, created by your first deploy. The region is fixed at creation. Attached databases are placed near the environment automatically, while observability data goes to the ingest region for the matching residency zone. See [Regions](https://mastra.ai/docs/mastra-platform/regions) for supported regions and database placement, along with observability co-location. The number of environments per project depends on your plan.
 
 ## List environments
 
@@ -92,7 +92,7 @@ mastra env db create staging --kind turso --name my-project-staging-db
 
 If you'd rather share one database across every environment, attach it with `--shared` instead: `mastra env db create --kind turso --shared`.
 
-An environment can only use one database per provider. If the project already has a shared (`--shared`) database of the same provider, attaching an environment-scoped one is rejected with a variable name conflict, delete the shared database with `mastra env db delete` first. Deleting a database destroys it with the provider along with all of its data, so export anything you need to keep. See [Hosted databases](https://mastra.ai/docs/mastra-platform/database) for the full scoping model.
+Each environment can use one database per provider. An existing shared (`--shared`) database from the same provider creates a variable-name conflict with an environment-scoped database. Export any data you need to keep before running `mastra env db delete`, because this command destroys the shared provider database and its data. See [Hosted databases](https://mastra.ai/docs/mastra-platform/database) for the full scoping model.
 
 ## Delete an environment
 

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

@@ -65,7 +65,7 @@ Templates are the fastest way to get started. The platform creates a new reposit
 
 4. Add any template-specific environment variables (for example, AI provider API keys). The platform seeds `MASTRA_GATEWAY_API_KEY` and `MASTRA_PLATFORM_ACCESS_TOKEN` automatically so that template code that talks to the Gateway works on the first deploy.
 
-5. Select **Create project**. The platform creates the repository, writes a `.mastra-project.json` config file into it, provisions the managed databases, and triggers the initial Studio and Server deploys.
+5. Select **Create project**. The platform creates the repository with a `.mastra-project.json` config file, provisions its managed databases, then triggers the initial Studio and Server deploys.
 
 The initial deploy waits for managed databases to finish provisioning before it starts, so the template's first build sees the database connection environment variables.
 
@@ -109,7 +109,7 @@ Only one build per deploy target runs at a time. If a new push arrives while a b
 
 ### Manual GitHub deploys
 
-You can also trigger a deploy from the dashboard without pushing. Open the project, select **Deploy from GitHub**, pick the target (Studio, Server, or both) and a branch, and submit. The platform runs the deploy against the head commit of that branch and records the trigger as a **GitHub Workflow** deploy.
+You can also trigger a deploy from the dashboard without pushing. Open the project and select **Deploy from GitHub**. Choose the target (Studio, Server, or both) together with a branch, then submit. The platform runs the deploy against the head commit of that branch and records the trigger as a **GitHub Workflow** deploy.
 
 ## Track deploys
 

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

@@ -65,7 +65,7 @@ Observability ingest runs in two regions today: **US** (Iowa, `us-central1`) and
 | `pdx`, `iad`, `sfo`, `us` shorthand | US (Iowa)            |
 | `ams`, `eu` shorthand               | EU (Amsterdam)       |
 
-Compute and databases can be placed in more Railway and provider regions than observability supports, so co-location isn't perfect for every combination. A `us`-zone environment always sends telemetry to US ingest, and an `eu`-zone environment always sends telemetry to EU ingest, even if the underlying Railway region is a specific city not directly served by an ingest endpoint. Data residency is preserved at the zone level. Telemetry from an `eu` environment never crosses into the US.
+Railway and database providers offer more regions than observability ingest, so some combinations can't be fully co-located. Environments in the `us` zone always send telemetry to US ingest, while those in the `eu` zone use EU ingest. This routing applies even when the underlying Railway region is a city without a dedicated ingest endpoint. Data residency is preserved at the zone level. Telemetry from an `eu` environment never crosses into the US.
 
 ## Related
 

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

@@ -48,7 +48,7 @@ You get a stable API endpoint with environment variable management and custom do
 
    If you're not already authenticated, the CLI prompts you to log in. It stores your credentials locally and any subsequent CLI commands use these credentials.
 
-   The command runs `mastra build`, uploads the artifact, builds a Docker image, and deploys it. On first deploy, the CLI creates a `.mastra-project.json` file linking your local project to the platform. Commit this file so subsequent deploys and CI/CD target the same project.
+   The command runs `mastra build` and uploads its artifact, then builds and deploys a Docker image. On first deploy, the CLI creates a `.mastra-project.json` file linking your local project to the platform. Commit this file so subsequent deploys and CI/CD target the same project.
 
    > **Note:** Environment variables from `.env`, `.env.local`, and `.env.production` are included automatically. On the first deploy, these seed the project if no env vars are set yet. After that, manage env vars through the web dashboard. Review and sanitize these files before first deploy to avoid uploading development-only or personal secrets.
 
@@ -60,7 +60,7 @@ You get a stable API endpoint with environment variable management and custom do
 
 ## Deploy lifecycle
 
-A deploy transitions through **queued → uploading → building → deploying → running** (or **failed**, **cancelled**, **crashed**, or **stopped**). A project runs one build at a time. When multiple deploys queue up, the latest proceeds and the rest are cancelled. Builds running longer than 15 minutes are automatically failed. The first deploy provisions infrastructure and seeds environment variables from your local `.env`. Your server URL remains stable across deploys.
+Each project runs one build at a time as its deploy transitions through **queued → uploading → building → deploying → running** (or **failed**, **cancelled**, **crashed**, or **stopped**). When multiple deploys queue up, the latest proceeds and the rest are cancelled. Builds running longer than 15 minutes are automatically failed. The first deploy provisions infrastructure and seeds environment variables from your local `.env`. Your server URL remains stable across deploys.
 
 ## Idle behavior
 
@@ -146,9 +146,9 @@ Automate deployments from GitHub Actions, GitLab CI, or any CI provider. After y
    mastra auth tokens create ci-deploy
    ```
 
-   The CLI prints the token once. Copy it immediately — it cannot be retrieved again.
+   The CLI prints the token once. Copy it immediately because it can't be retrieved again.
 
-2. Add the token as a secret in your CI provider. In GitHub Actions, go to **Settings → Secrets and variables → Actions** and create a secret named `MASTRA_API_TOKEN`.
+2. Add the token as a secret in your CI provider. In GitHub Actions, go to **Settings → Secrets and variables → Actions** and create the `MASTRA_API_TOKEN` secret.
 
 3. Ensure your `.mastra-project.json` file is committed to the repository. The CLI reads the `organizationId` and `projectId` from this file to target the correct project during CI deploys.
 

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

@@ -70,7 +70,7 @@ To run the same codebase across `production` and `staging`, use [`mastra deploy
 
 ## Create a new project non-interactively
 
-`mastra deploy` can create a project on first run. If `--project <name>` doesn't match an existing project, the CLI uses the value as the new project name and creates it after confirmation. Combined with `--yes`, this is fully scriptable:
+On its first run, `mastra deploy` can create a project. When `--project <name>` doesn't match an existing project, the CLI treats the value as a new project name and creates it after confirmation. Add `--yes` to make this flow fully scriptable:
 
 ```bash
 mastra deploy --project "my-new-project" --yes

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

@@ -74,7 +74,7 @@ A theme can persist, disappear, split, merge, or return across snapshots. Treat
 
 ## 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.
+1. Use the **Agent** selector to switch between agents after their first themes are ready and analysis becomes available.
 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.

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

@@ -85,7 +85,7 @@ export const mastra = new Mastra({
 - `stop()` tears down the remote sandbox while preserving its recovery checkpoint when it has one.
 - `destroy()` also releases the recovery checkpoint associated with a caller-supplied recovery `id`.
 
-One statically configured `PlatformSandbox` is shared by every request and agent using that configuration. Requests and memory threads don't receive separate sandboxes automatically. `PlatformFilesystem` is also a separate provider: configuring both providers doesn't mount the environment bucket inside the sandbox.
+A statically configured `PlatformSandbox` is shared across every request and agent using that configuration rather than creating separate sandboxes for requests or memory threads. `PlatformFilesystem` is also a separate provider: configuring both providers doesn't mount the environment bucket inside the sandbox.
 
 When your agent needs another isolated environment, for example a per-task sandbox, a per-user tenant, or a background job that shouldn't touch shared shell state, construct another `PlatformSandbox`:
 

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

@@ -119,8 +119,8 @@ await agent.stream('Hello', {
 
 You can use this history in two ways:
 
-- **Automatic inclusion**: Mastra automatically fetches recent messages and includes them in the context window. By default, the last 10 messages keep agents grounded in the conversation. You can adjust this number with `lastMessages`, but in most cases you don't need to think about it.
-- [**Manual querying**](#querying): For more control, use the `recall()` function to query threads and messages directly. This lets you choose exactly which memories are included in the context window, or fetch messages to render conversation history in your UI.
+- **Automatic inclusion**: Mastra automatically includes recent messages in the context window. The default of 10 messages keeps agents grounded in the conversation. Adjust it with `lastMessages` when needed.
+- [**Manual querying**](#querying): For more control, query threads and messages directly with `recall()`. Use the results to choose which memories enter the context window or to render conversation history in your UI.
 
 > **Tip:** When memory is enabled, [Studio](https://mastra.ai/docs/studio/overview) uses message history to display past conversations in the chat sidebar.
 
@@ -230,7 +230,7 @@ const thread = await memory.getThreadById({ threadId: 'thread-123' })
 
 ### Messages
 
-Once you have a thread, use [`recall()`](https://mastra.ai/reference/memory/recall) to retrieve its messages. It supports pagination, date filtering, and [semantic search](https://mastra.ai/docs/memory/semantic-recall).
+Once you have a thread, use [`recall()`](https://mastra.ai/reference/memory/recall) to retrieve its messages. It supports pagination and [semantic search](https://mastra.ai/docs/memory/semantic-recall), with optional date filtering.
 
 Basic recall returns all messages from a thread:
 

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

@@ -31,7 +31,7 @@ export const agent = new Agent({
 
 **For AI agents:** Using Observational Memory requires a storage provider! You either need to set it on the Mastra instance at `src/mastra/index.ts` or pass it to the Agent constructor.
 
-The following script creates a local LibSQL database, enables Observational Memory, and uses one resource and thread across two agent calls:
+The following script creates a local LibSQL database and enables Observational Memory before using one resource and thread across two agent calls:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -214,11 +214,11 @@ When message history tokens exceed a threshold (default: 30,000), the Observer c
 
 OM uses fast local token estimation for this thresholding work. Text is estimated with `tokenx`, while image parts use provider-aware heuristics so multimodal conversations still trigger observation at the right time. The same applies to image-like `file` parts when a transport normalizes an uploaded image as a file instead of an image part. For example, OpenAI image detail settings can materially change when OM decides to observe.
 
-The Observer can also see attachments in the history it reviews. OM keeps readable placeholders like `[Image #1: reference-board.png]` or `[File #1: floorplan.pdf]` in the transcript for readability, and forwards the actual attachment parts alongside the text. Image-like `file` parts are upgraded to image inputs for the Observer when possible, while non-image attachments are forwarded as file parts with normalized token counting. This applies to both normal thread observation and batched resource-scope observation.
+The Observer can also see attachments in the history it reviews. For readability, OM keeps placeholders such as `[Image #1: reference-board.png]` or `[File #1: floorplan.pdf]` in the transcript while forwarding the actual attachments beside the text. When possible, image-like `file` parts become image inputs for the Observer. Other attachments remain file parts and use normalized token counting. This applies to both normal thread observation and batched resource-scope observation.
 
 ### Extractors
 
-Use extractors when you want OM to persist specific values alongside observations. Built-in values such as **current task**, **suggested response**, and **thread title** use the same extraction pipeline as custom values.
+Use extractors when you want OM to persist specific values alongside observations. Built-in values use the same extraction pipeline as custom values. They include **current task** and **suggested response**, along with **thread title**.
 
 The following example extracts a compact user profile from observations:
 
@@ -380,7 +380,7 @@ new Agent({
 })
 ```
 
-You can also pass an allowlist of mimeType globs (for example `['image/*']`) to forward only the kinds the Observer can handle. Alternatively, set `observeAttachments: 'auto'` to let Mastra decide from the provider capabilities registry: attachments are forwarded when the Observer model supports multimodal input and dropped otherwise, falling back to `true` when no capability data is available for the model.
+You can also pass an allowlist of mimeType globs (for example `['image/*']`) to forward only the kinds the Observer can handle. Alternatively, set `observeAttachments: 'auto'` so Mastra consults the provider capabilities registry. It forwards attachments when the Observer model supports multimodal input and drops them otherwise. If capability data is unavailable for the model, the setting falls back to `true`.
 
 ```md
 Date: 2026-01-15
@@ -426,7 +426,7 @@ With [`shareTokenBudget`](https://mastra.ai/reference/memory/observational-memor
 
 ### Retrieval mode
 
-Normal OM compresses messages into observations, which is great for staying on task, but the original wording is gone. Retrieval mode fixes this by keeping each observation group linked to the raw messages that produced it. When the agent needs exact wording, tool output, or chronology that the summary compressed away, it can call a `recall` tool to page through the source messages.
+Normal OM compresses messages into observations, which is great for staying on task, but the original wording is gone. Retrieval mode fixes this by keeping each observation group linked to the raw messages that produced it. The agent can call a `recall` tool to recover source details compressed by the summary, including exact wording and tool output as well as chronology.
 
 #### Browsing only
 
@@ -716,23 +716,23 @@ When message tokens reach the `messageTokens` threshold, buffered chunks activat
 
 Buffered observations also include continuation hints, a suggested next response and the current task, so the main agent maintains conversational continuity after activation shrinks the context window.
 
-If the agent produces messages faster than the Observer can process them, the `blockAfter` safety threshold lets activation overshoot the retention target instead of activating fewer chunks. It never activates more chunks than are needed to reach that target, and with the default settings it changes nothing. A synchronous observation runs when the `messageTokens` threshold is reached and buffered activation didn't happen. Buffered activation usually preserves a minimum remaining context (the smaller of \~1k tokens or the configured retention floor), but a single buffered chunk that covers the whole pending window still activates and can leave less.
+When message production outpaces the Observer, the `blockAfter` safety threshold allows activation to overshoot the retention target instead of using fewer chunks. Activation still uses no more chunks than needed to reach the target, and the default settings remain unaffected. A synchronous observation runs when the `messageTokens` threshold is reached and buffered activation didn't happen. Buffered activation usually preserves a minimum remaining context (the smaller of \~1k tokens or the configured retention floor), but a single buffered chunk that covers the whole pending window still activates and can leave less.
 
 Reflection works similarly, the Reflector runs in the background when observations reach a fraction of the reflection threshold.
 
 ### Settings
 
-| Setting                               | Default | What it controls                                                                                                                                                                                                                                                                                                                                                      |
-| ------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `observation.bufferTokens`            | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens`. With the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).                                                                                                                                                                                     |
-| `observation.bufferActivation`        | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history.                                                                                                                                                                                 |
-| `observation.blockAfter`              | `1.2`   | Safety net if buffering can't keep up. Values from 1 up to (but not including) 100 multiply `messageTokens`: at `1.2`, the threshold is 36k tokens (1.2 × 30k). Above it, activation may overshoot the retention target instead of activating fewer chunks. Values of 100 or more are absolute token counts (e.g. `50_000`) and must be greater than `messageTokens`. |
-| `activateAfterIdle`                   | none    | Forces buffered observations to activate after a period of inactivity, even before `observation.messageTokens` is reached. Accepts a numeric millisecond value such as `300_000`, duration strings like `"5m"` or `"1hr"`, or `"auto"` for a provider-aware prompt cache TTL.                                                                                         |
-| `activateOnProviderChange`            | `false` | Forces buffered observations to activate when the next step uses a different `provider/model` than the one that produced the latest assistant step. Use this when switching providers or models would invalidate prompt cache reuse.                                                                                                                                  |
-| `reflection.bufferActivation`         | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                                                                                                                                                                                                  |
-| `reflection.activateAfterIdle`        | none    | Opts buffered reflections into idle activation. Reflections don't inherit top-level `activateAfterIdle`.                                                                                                                                                                                                                                                              |
-| `reflection.activateOnProviderChange` | `false` | Opts buffered reflections into provider-change activation. Reflections don't inherit top-level `activateOnProviderChange`.                                                                                                                                                                                                                                            |
-| `reflection.blockAfter`               | `1.2`   | Safety threshold for reflection. Same value format as observation (absolute values must be greater than `observationTokens`), but above it reflection runs synchronously when no buffered reflection is ready to activate.                                                                                                                                            |
+| Setting                               | Default | What it controls                                                                                                                                                                                                                                                                                                                                                                 |
+| ------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `observation.bufferTokens`            | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens`. With the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).                                                                                                                                                                                                |
+| `observation.bufferActivation`        | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history.                                                                                                                                                                                            |
+| `observation.blockAfter`              | `1.2`   | Safety net if buffering can't keep up. Values from 1 up to (but not including) 100 multiply `messageTokens`. For example, `1.2` creates a threshold of 36k tokens (1.2 × 30k), above which activation may overshoot the retention target rather than use fewer chunks. Values of 100 or more are absolute token counts (e.g. `50_000`) and must be greater than `messageTokens`. |
+| `activateAfterIdle`                   | none    | Forces buffered observations to activate after a period of inactivity, even before `observation.messageTokens` is reached. Accepts a numeric millisecond value such as `300_000`, duration strings like `"5m"` or `"1hr"`, or `"auto"` for a provider-aware prompt cache TTL.                                                                                                    |
+| `activateOnProviderChange`            | `false` | Forces buffered observations to activate when the next step uses a different `provider/model` than the one that produced the latest assistant step. Use this when switching providers or models would invalidate prompt cache reuse.                                                                                                                                             |
+| `reflection.bufferActivation`         | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                                                                                                                                                                                                             |
+| `reflection.activateAfterIdle`        | none    | Opts buffered reflections into idle activation. Reflections don't inherit top-level `activateAfterIdle`.                                                                                                                                                                                                                                                                         |
+| `reflection.activateOnProviderChange` | `false` | Opts buffered reflections into provider-change activation. Reflections don't inherit top-level `activateOnProviderChange`.                                                                                                                                                                                                                                                       |
+| `reflection.blockAfter`               | `1.2`   | Safety threshold for reflection. Same value format as observation (absolute values must be greater than `observationTokens`), but above it reflection runs synchronously when no buffered reflection is ready to activate.                                                                                                                                                       |
 
 If you're relying on prompt caching, set `activateAfterIdle` to `"auto"` or to a specific cache TTL. That way, once a thread has been idle long enough for the cache to expire, the next request can activate buffered observations first and send a smaller compressed context window.
 
@@ -784,7 +784,7 @@ const memory = new Memory({
 
 Setting `bufferTokens: false` disables both observation and reflection async buffering. See [async buffering configuration](https://mastra.ai/reference/memory/observational-memory) for the full API.
 
-> **Note:** Async buffering isn't supported with `scope: 'resource'`. It's automatically disabled in resource scope.
+> **Note:** Resource scope automatically disables async buffering.
 
 ## Observer Context Optimization
 

package/.docs/docs/memory/overview.md

@@ -116,7 +116,7 @@ Use memory when your agent needs to maintain multi-turn conversations that refer
 
    Visit [Memory Class](https://mastra.ai/reference/memory/memory-class) for a full list of configuration options.
 
-5. Call your agent, for example in [Studio](https://mastra.ai/docs/studio/overview). Inside Studio, start a new chat with your agent and take a look at the right sidebar. It'll now display various memory-related information.
+5. Call your agent, for example in [Studio](https://mastra.ai/docs/studio/overview). Inside Studio, start a new chat with your agent and take a look at the right sidebar. It'll now display memory details.
 
 ## Message history
 

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

@@ -275,7 +275,7 @@ Schema-based working memory uses **merge semantics**, meaning the agent only nee
 ## Choosing between template and schema
 
 - Use a **template** (Markdown) if you want the agent to maintain memory as a free-form text block, such as a user profile or scratchpad. Templates use **replace semantics**: the agent must provide the complete memory content on each update.
-- Use a **schema** if you need structured, type-safe data that can be validated and programmatically accessed as JSON. The `workingMemory.schema` field accepts any `PublicSchema`-compatible schema (including Zod v3, Zod v4, JSON Schema, or already-standard schemas). Schemas use **merge semantics**: the agent only provides fields to update, and existing fields are preserved.
+- Use a **schema** for structured, type-safe JSON data that supports validation and programmatic access. The `workingMemory.schema` field accepts any `PublicSchema`-compatible schema, such as Zod v3 or v4. JSON Schema and already-standard schemas are also supported. **Merge semantics** preserve existing fields when the agent provides only the fields to update.
 - Only one mode can be active at a time: setting both `template` and `schema` isn't supported.
 
 ## Example: Multi-step retention

package/.docs/docs/observability/feedback.md

@@ -155,7 +155,7 @@ The local runtime exposes the list route at `/api/observability/feedback` and an
 
 [`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter) forwards emitted feedback events to Mastra Platform automatically because the hosted query API doesn't provide a creation route.
 
-If your application adds feedback after an agent or workflow response using only its `traceId`, configure `MastraStorageExporter` alongside `MastraPlatformExporter`. The storage exporter keeps the trace available for `addFeedback()` to rehydrate, and the Platform exporter forwards the resulting feedback event. Exporting a trace to Platform doesn't make it available to the application's local storage.
+If your application adds feedback after an agent or workflow response using only its `traceId`, configure `MastraStorageExporter` alongside `MastraPlatformExporter`. The storage exporter keeps the trace available for `addFeedback()` to rehydrate, while the Platform exporter forwards the resulting feedback event without adding the trace to the application's local storage.
 
 See [Observability on Mastra Platform](https://mastra.ai/docs/mastra-platform/observability) for the combined exporter configuration.
 

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

@@ -78,7 +78,7 @@ export const mastra = new Mastra({
 
 ### Custom loggers
 
-Custom `IMastraLogger` implementations keep working: Mastra falls back to a dual-write wrapper that forwards log calls to observability. This fallback doesn't add `trace_id`/`span_id` to the logger's native output and is deprecated. To get trace-correlated output, implement the `__attachObservability()` adapter hook from `@mastra/core/logger`:
+Custom `IMastraLogger` implementations keep working: Mastra uses a deprecated dual-write fallback that forwards log calls to observability without adding `trace_id` or `span_id` to the logger's native output. To get trace-correlated output, implement the `__attachObservability()` adapter hook from `@mastra/core/logger`:
 
 ```typescript
 import { MastraLogger, buildLogRecordData } from '@mastra/core/logger'

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

@@ -144,7 +144,7 @@ export const mastra = new Mastra({
 })
 ```
 
-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.
+If `environment` isn't set, runs started through `mastra dev` resolve to `development` (even though the dev server itself runs with `NODE_ENV=production`); otherwise Mastra falls back to `process.env.NODE_ENV`. If none of these are 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/sandbox/lsp.md

@@ -149,7 +149,7 @@ lsp: {
 },
 ```
 
-`binaryOverrides` maps a built-in server ID to its full startup command. `searchPaths` adds package roots whose `node_modules` may contain binaries or required modules. You can also set `packageRunner`, such as `pnpm dlx`, as a last-resort fallback. Package-runner fallback is disabled by default because it may install software or hang in some project layouts.
+`binaryOverrides` maps a built-in server ID to its full startup command. `searchPaths` adds package roots whose `node_modules` may contain required modules or binaries. As a last-resort fallback, you can set a `packageRunner` such as `pnpm dlx`. Package-runner fallback is disabled by default because it may install software or hang in some project layouts.
 
 `diagnosticTimeout` controls how long the direct `getDiagnostics()` and `getDiagnosticsMulti()` APIs wait for diagnostics. The agent inspection tool currently waits up to five seconds.
 

package/.docs/docs/sandbox/overview.md

@@ -264,7 +264,7 @@ The example mounts the filesystem inside the resolver because static `mounts` ca
 
 With a static sandbox, Mastra knows which capabilities the backend supports and only gives the agent the corresponding tools. Application code should also check that an optional capability is available before using it.
 
-With a [resolver-backed sandbox](#sandboxes-per-user-or-thread), the backend isn't known until a request runs, so Mastra initially makes all sandbox tools available. If the resolved backend doesn't support the tool the agent calls, the call fails with `SandboxFeatureNotSupportedError`.
+Because a [resolver-backed sandbox](#sandboxes-per-user-or-thread) isn't known until request time, Mastra initially exposes every sandbox tool. Calling one unsupported by the resolved backend fails with `SandboxFeatureNotSupportedError`.
 
 ## Background processes
 

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

@@ -305,7 +305,7 @@ export const colorAgent = new Agent({
 
 ## Use MastraClient on the server
 
-You can also use `MastraClient` in server-side environments such as API routes, serverless functions, or actions. The usage remains the same, but you may need to recreate the response for your client:
+Server-side API routes and serverless functions, including actions, can also use `MastraClient`. The usage is unchanged, although you may need to recreate the response for your client:
 
 ```typescript
 export async function action() {

package/.docs/docs/server/overview.md

@@ -66,7 +66,7 @@ Mastra exposes OpenAI-compatible Responses and Conversations routes that let you
 
 These APIs are currently experimental.
 
-Use `agent_id` to select the Mastra agent that should handle the request. Initial requests target an agent directly, and stored follow-up turns can continue with `previous_response_id`. You can also pass `model` to override the agent's configured model for a single request. If you omit `model`, Mastra uses the model already configured on the agent.
+Use `agent_id` to select the Mastra agent that should handle the request. Initial requests target an agent directly. Stored follow-up turns can continue through `previous_response_id`. Pass `model` to override the configured model for one request, or omit it to use the agent's existing model.
 
 The Responses routes support streaming, function calling (tools), stored continuations with `previous_response_id`, conversation threads through `conversation_id`, provider-specific passthrough with `providerOptions`, and JSON output through `text.format`.
 

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

@@ -6,7 +6,7 @@
 
 Mastra uses a publish/subscribe (pub/sub) system as its internal event bus. Components publish events to topics, and other components subscribe to those topics to react. The backend you configure decides how far those events travel: within one process or across processes on one host, or alternatively across separate instances.
 
-You set the backend once on the `Mastra` instance, and the rest of the system uses it without changes. By default, Mastra uses an in-process backend that needs no setup.
+Set the backend once on the `Mastra` instance for use throughout the system. The default is an in-process backend that requires no setup.
 
 ## How Mastra uses PubSub
 

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

@@ -152,7 +152,7 @@ You can also use `requestContext` with other options like `agents`, `workflows`,
 
 ### Dynamic instructions
 
-Agent instructions can be provided as an async function, enabling you to resolve prompts at runtime. Combined with `requestContext`, this enables patterns like:
+Provide agent instructions through an async function to resolve prompts at runtime. Together with `requestContext`, this supports patterns like:
 
 - **Personalization**: Tailor instructions based on user attributes, preferences, or tier
 - **Localization**: Adjust tone, language, or behavior based on locale
@@ -270,7 +270,7 @@ auth: {
 }
 ```
 
-When the resource ID is derived this way, clients can omit `memory.resource` from agent generate and stream request bodies, the server-derived value is used instead (and always takes precedence over any client-provided value). If a request uses memory and neither the body nor the request context provides a resource ID, the server responds with a 400 error.
+When the resource ID is derived this way, clients can omit `memory.resource` from agent generate and stream request bodies. The server-derived value is used instead and always takes precedence over a client-provided value. If a request uses memory and neither the body nor the request context provides a resource ID, the server responds with a 400 error.
 
 You can also set these keys manually in middleware:
 

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

@@ -337,7 +337,7 @@ bun add @mastra/nestjs@latest
 
 ## Configuration
 
-Initialize your app as usual, then create a `MastraServer` by passing in the `app` and your main `mastra` instance from `src/mastra/index.ts`. Calling `init()` automatically registers Mastra middleware and all available endpoints. You can continue adding your own routes as normal, either before or after `init()`, and they’ll run alongside Mastra’s endpoints.
+Initialize your app as usual, then create a `MastraServer` by passing in the `app` and your main `mastra` instance from `src/mastra/index.ts`. Calling `init()` automatically registers Mastra middleware and all available endpoints. Continue adding your own routes either before or after `init()`. They run alongside Mastra’s endpoints.
 
 **Elysia**:
 

package/.docs/docs/skills.md

@@ -6,7 +6,7 @@
 
 Skills are reusable instructions that teach agents how to perform specific tasks. They follow the [Agent Skills specification](https://agentskills.io).
 
-You can attach skills directly to an agent through its `skills` config, or configure them on a [workspace](https://mastra.ai/docs/sandbox/skills). Attach them to the agent when the skills belong to that specific agent and you want to define them in code with no workspace required. Use a workspace when you want skills discovered from the filesystem and shared across every agent that uses it. This page covers the agent-level approach, defining skills in code and loading them from files, plus resolving them per request.
+Attach skills directly through an agent's `skills` config, or configure them on a [workspace](https://mastra.ai/docs/sandbox/skills). Agent-level skills belong to one agent and can be defined in code without a workspace, while workspace skills are discovered from the filesystem and shared by every agent using that workspace. This page explains how to define and load agent-level skills with per-request resolution.
 
 ## When to use agent-level skills
 

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

@@ -51,7 +51,7 @@ Run the `mastra studio` command:
 mastra studio
 ```
 
-Open [localhost:3000](http://localhost:3000) in your browser to see the Studio UI. By default, it will attempt to connect to a Mastra server running at `http://localhost:4111`. If it doesn't find one there, you'll see a form where you can enter your Mastra instance URL and API prefix.
+Open [localhost:3000](http://localhost:3000) in your browser to see the Studio UI. By default, it connects to a Mastra server at `http://localhost:4111`; when no server is available, the UI displays a form for entering your Mastra instance URL and API prefix.
 
 The command uses Node's built-in `http` module and [`serve-handler`](https://www.npmjs.com/package/serve-handler) to serve the static files.
 

package/.docs/docs/studio/editor.md

@@ -77,7 +77,7 @@ An instruction block can include values from the current request. For example, `
 
 ### Prompt blocks
 
-A prompt block is a saved piece of instruction text that can be used by more than one agent. Create one under **Prompts**, publish it, then open an agent's **Instructions** section and select **Add block**.
+A prompt block is a saved piece of instruction text that can be used by more than one agent. Create and publish one under **Prompts**. Then open an agent's **Instructions** section and select **Add block**.
 
 For example, agents for support, returns, and order status may all need the same refund policy. Save the policy as a prompt block and add it to each agent. When the policy changes, update and publish the block once instead of editing three agents.
 

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

@@ -41,7 +41,7 @@ Once the server is running, you can:
 - Open the Studio UI at [`localhost:4111`](http://localhost:4111/) to interact with your agents, workflows, and tools.
 - Visit [`localhost:4111/swagger-ui`](http://localhost:4111/swagger-ui) to discover and interact with the underlying REST API.
 
-While Studio is running, you can edit your [agents](https://mastra.ai/docs/agents/overview), [workflows](https://mastra.ai/docs/workflows/overview), and other parts of your Mastra application in real time.
+Studio lets you edit your [agents](https://mastra.ai/docs/agents/overview), [workflows](https://mastra.ai/docs/workflows/overview), and other parts of your Mastra application in real time.
 
 ## Deploy Studio