@mastra/mcp-docs-server 1.2.18 → 1.2.19-alpha.13

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

@@ -139,6 +139,24 @@ This list isn't exhaustive. To view all endpoints, run `mastra dev` and visit `h
 
 To add your own endpoints, see [Custom API Routes](https://mastra.ai/docs/server/custom-api-routes).
 
+## Graceful shutdown and rolling deploys
+
+By default, the generated server handles `SIGINT` and `SIGTERM`. It stops accepting connections, waits up to [`server.drainTimeout`](https://mastra.ai/reference/configuration) for active requests and streams, then runs `mastra.shutdown()`. The drain timeout defaults to 5 seconds. A second signal terminates the process immediately. See [`server.handleShutdownSignals`](https://mastra.ai/reference/configuration) if you need to manage signals yourself.
+
+Increase `drainTimeout` when your hosting platform's termination grace period can accommodate longer turns. Keep enough time after the drain for shutdown cleanup.
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+
+export const mastra = new Mastra({
+  server: {
+    drainTimeout: 240_000,
+  },
+})
+```
+
+A plain `agent.stream()` call can't resume after its server process exits. If a stream ends without its expected terminal event, treat the turn as interrupted and let the client retry or reconcile it. Use [durable agents](https://mastra.ai/docs/harness/durable-agents) when turns must survive process replacement. [Crash recovery](https://mastra.ai/docs/harness/durable-agents) requires shared persistent run storage and idempotent tools. Replaying missed events after a restart also requires a shared persistent cache such as Redis because the default event cache is in-memory. Multi-replica recovery doesn't yet use a distributed lease.
+
 ## Troubleshooting
 
 ### Memory errors during build
@@ -154,4 +172,5 @@ NODE_OPTIONS="--max-old-space-size=4096" mastra build
 - [Server Overview](https://mastra.ai/docs/server/overview): Configure server behavior, middleware, and authentication
 - [Server Adapters](https://mastra.ai/docs/server/server-adapters): Use Express or Hono instead of `mastra build`
 - [Custom API Routes](https://mastra.ai/docs/server/custom-api-routes): Add custom HTTP endpoints
+- [Durable Agents](https://mastra.ai/docs/harness/durable-agents): Persist agent runs so they survive process restarts
 - [Configuration Reference](https://mastra.ai/reference/configuration): Full configuration options

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

@@ -29,7 +29,7 @@ Subscribes to workflow events on the [PubSub](https://mastra.ai/docs/server/pubs
 
 In a split deployment, the orchestration worker pulls events from a distributed PubSub backend and delegates step execution back to the API over HTTP. In-process, it runs steps directly.
 
-The orchestration worker requires a PubSub backend that supports pull mode (e.g., [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams) or [`GoogleCloudPubSub`](https://mastra.ai/reference/pubsub/google-cloud-pubsub)).
+The orchestration worker requires a PubSub backend that supports pull mode (e.g., [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams), [`ValkeyStreamsPubSub`](https://mastra.ai/reference/pubsub/valkey-streams), or [`GoogleCloudPubSub`](https://mastra.ai/reference/pubsub/google-cloud-pubsub)).
 
 ### Scheduler worker
 
@@ -104,7 +104,7 @@ Any [supported storage backend](https://mastra.ai/reference/workers/overview) wo
 
 Run the same build artifact in multiple containers, each with a different [`MASTRA_WORKERS`](https://mastra.ai/reference/workers/overview) value to control which worker starts in each process.
 
-Split deployments require a distributed PubSub backend ([`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams) or [`GoogleCloudPubSub`](https://mastra.ai/reference/pubsub/google-cloud-pubsub)), a shared [storage backend](https://mastra.ai/reference/workers/overview), and network connectivity between the orchestration worker and the API.
+Split deployments require a distributed PubSub backend ([`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams), [`ValkeyStreamsPubSub`](https://mastra.ai/reference/pubsub/valkey-streams), or [`GoogleCloudPubSub`](https://mastra.ai/reference/pubsub/google-cloud-pubsub)), a shared [storage backend](https://mastra.ai/reference/workers/overview), and network connectivity between the orchestration worker and the API.
 
 ### Select workers
 

package/.docs/docs/evals/built-in-scorers.md

@@ -22,6 +22,7 @@ These scorers evaluate how correct, truthful, and complete your agent's answers
 - [`tool-call-accuracy`](https://mastra.ai/reference/evals/tool-call-accuracy): Evaluates whether the LLM selects the correct tool from available options (`0-1`, higher is better)
 - [`trajectory-accuracy`](https://mastra.ai/reference/evals/trajectory-accuracy): Evaluates the expected action sequence for all span types. Covered spans include tool and model activity plus workflow steps (`0-1`, higher is better)
 - [`prompt-alignment`](https://mastra.ai/reference/evals/prompt-alignment): Measures how well agent responses align with user prompt intent, requirements, completeness, and format (`0-1`, higher is better)
+- [`multi-turn-judge`](https://mastra.ai/reference/evals/multi-turn-judge): Grades every assistant turn of a [multi-turn conversation](https://mastra.ai/docs/evals/multi-turn) against a plain-English criterion (`0` or `1`)
 
 ### Context quality
 

package/.docs/docs/evals/multi-turn.md

@@ -35,6 +35,8 @@ const result = await runEvals({
 
 Each turn runs `agent.generate()` with the same thread ID, so the agent sees the full conversation history. Scorers receive the accumulated output messages from all turns.
 
+> **Prebuilt LLM judges grade one turn:** Prebuilt LLM-judge scorers (rubric, answer relevancy, faithfulness, and the others listed in [Scorer compatibility](#scorer-compatibility)) read a single assistant message, so with `inputs` they grade only the last turn's response. For semantic grading across a conversation, use [`createMultiTurnJudgeScorer()`](https://mastra.ai/reference/evals/multi-turn-judge), which grades every assistant turn against one criterion, or per-turn [`turns[].scorers`](#per-turn-assertions-with-turns), where each turn grades its own output.
+
 ## Memory is required for cross-turn recall
 
 Multi-turn recall depends on the agent having a **memory store configured**. The shared thread ID is what lets each turn see the earlier ones, but a thread only persists history when the agent has memory. If the agent has no memory configured, the turns still run sequentially and their outputs still accumulate for scoring, but the agent won't recall earlier turns (each input runs in isolation). `runEvals` logs a warning when you use `inputs` on an agent without memory.
@@ -70,6 +72,85 @@ These details matter when writing scorers for multi-turn items:
 - **`run.output` is the accumulated output from every turn.** Output-based scorers: `checks.includes`, `checks.calledTool`, `checks.similarity`, and similar: evaluate the whole conversation. For example, `checks.calledTool('get_weather', { times: 2 })` counts calls across all turns.
 - **`run.input` is only the first turn's input.** Scorers that compare input against output (faithfulness, answer relevancy, and other input-relative LLM scorers) only see the first user message, not the full conversation. Prefer output-based checks for multi-turn, or build scorers that read the accumulated `run.output` directly.
 
+### Scorer compatibility
+
+Accumulated output only helps if the scorer reads all of it:
+
+| Scorer                                                                                                                                                                                                                         | What it sees with `inputs`                                                                                        |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| [Quick Checks](https://mastra.ai/docs/evals/quick-checks): `checks.calledTool`, `checks.includes`, `checks.similarity`, `checks.noToolErrors`, and the rest                                                                    | The whole conversation. Tool-call checks count calls across every turn, and text checks search all assistant text |
+| [Multi-turn Judge scorer](https://mastra.ai/reference/evals/multi-turn-judge)                                                                                                                                                  | Every assistant turn, graded together against one plain-English criterion                                         |
+| Prebuilt LLM-judge scorers: rubric, answer relevancy, answer similarity, faithfulness, hallucination, bias, toxicity, context precision, context recall, context relevance, noise sensitivity, prompt alignment, summarization | Only the last assistant message that carries text. Input-relative judges also see only the first turn's input     |
+| Trajectory scorers (`AgentScorerConfig.trajectory`)                                                                                                                                                                            | The last turn's span when traces are available, otherwise tool calls from all accumulated messages                |
+| Custom scorers                                                                                                                                                                                                                 | Whatever they read from `run.output`                                                                              |
+
+### Grading a whole conversation
+
+To judge every turn together, use [`createMultiTurnJudgeScorer()`](https://mastra.ai/reference/evals/multi-turn-judge). It builds a transcript of every assistant turn and asks a judge model whether the conversation satisfies one plain-English criterion, scoring `1` or `0`:
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { createMultiTurnJudgeScorer } from '@mastra/evals/scorers/prebuilt'
+import { weatherAgent } from '../agents'
+
+const result = await runEvals({
+  data: [
+    {
+      inputs: [
+        "How's the weather in London?",
+        'And Paris?',
+        'Should I pack an umbrella for London?',
+      ],
+    },
+  ],
+  target: weatherAgent,
+  scorers: [
+    {
+      scorer: createMultiTurnJudgeScorer({
+        model: 'anthropic/claude-haiku-4-5',
+        criterion:
+          'The agent provided forecasts for London and Paris, and gave weather-appropriate packing advice.',
+      }),
+      threshold: 1,
+    },
+  ],
+})
+```
+
+To grade something the criterion can't express, write your own scorer that reads the assistant messages out of `run.output`. [`extractAgentResponseMessages()`](https://mastra.ai/reference/evals/scorer-utils) returns the text of each assistant message, in order:
+
+```typescript
+import { createScorer } from '@mastra/core/evals'
+import { extractAgentResponseMessages } from '@mastra/evals/scorers/utils'
+import { z } from 'zod'
+
+export const conversationJudge = createScorer({
+  id: 'conversation-judge',
+  name: 'Conversation Judge',
+  description: 'Grades every assistant turn in a conversation against one criterion',
+  type: 'agent',
+  judge: {
+    model: 'anthropic/claude-haiku-4-5',
+    instructions: 'You grade multi-turn assistant transcripts against a single criterion.',
+  },
+})
+  .analyze({
+    description: 'Judge the transcript as a whole',
+    outputSchema: z.object({ satisfied: z.boolean(), reason: z.string() }),
+    createPrompt: ({ run }) => {
+      const transcript = extractAgentResponseMessages(run.output)
+        .map((text, index) => `Turn ${index + 1}: ${text}`)
+        .join('\n\n')
+
+      return `Grade this conversation:\n\n${transcript}\n\nCriterion: the assistant keeps the forecast consistent across turns.`
+    },
+  })
+  .generateScore(({ results }) => (results.analyzeStepResult?.satisfied ? 1 : 0))
+  .generateReason(({ results }) => results.analyzeStepResult?.reason ?? '')
+```
+
+Pass it to `runEvals` like any other scorer. See [Custom scorers](https://mastra.ai/docs/evals/custom-scorers) for the full `createScorer()` pipeline.
+
 ## Per-turn assertions with `turns`
 
 The `inputs` form scores the **accumulated** output as a whole, a single score over every turn's output. That can hide per-turn failures: an output-based check like `checks.includes('Brooklyn')` passes if _any_ turn mentions Brooklyn, even when the follow-up turn is broken.
@@ -175,4 +256,6 @@ await runEvals({
 
 - [`runEvals()` reference](https://mastra.ai/reference/evals/run-evals): Full API for `runEvals` parameters and returns
 - [Gates and verdicts](https://mastra.ai/docs/evals/gates-and-verdicts): Enforce hard requirements and quality thresholds
-- [Quick Checks](https://mastra.ai/docs/evals/quick-checks): Zero-LLM composable micro-scorers
+- [Quick Checks](https://mastra.ai/docs/evals/quick-checks): Zero-LLM composable micro-scorers
+- [Scorer utilities](https://mastra.ai/reference/evals/scorer-utils): Helpers for reading messages out of a scorer run
+- [Multi-turn Judge scorer](https://mastra.ai/reference/evals/multi-turn-judge): LLM judge that grades every assistant turn together

package/.docs/docs/evals/overview.md

@@ -115,15 +115,77 @@ For the step-level `scorers` API, see the [Step class reference](https://mastra.
 
 **Asynchronous execution**: Live evaluations run in the background without blocking your agent responses or workflow execution. Your AI systems remain responsive while live evaluations monitor them.
 
-**Sampling control**: The `sampling.rate` parameter (0-1) controls what percentage of outputs get scored:
+**Sampling control**: The `sampling.rate` parameter (0-1) controls what fraction of outputs get scored:
 
 - `1.0`: Score every single response (100%)
 - `0.5`: Score half of all responses (50%)
 - `0.1`: Score 10% of responses
 - `0.0`: Disable scoring
 
+Sampling is deterministic per trace: the decision is derived from the trace ID, not drawn at random. In practice:
+
+- Scorers configured at the same rate score the same traces, so their scores are comparable on shared traffic.
+- Re-running the same trace produces the same sampling decision, so sampled coverage is reproducible.
+
+When a run has no trace (observability not configured), the decision is derived from the run ID instead. If [trace sampling](https://mastra.ai/docs/observability/tracing/overview) declined the trace, scorers skip that run entirely, so scores aren't created for traces that were never stored.
+
+**Eligibility filters**: The optional `filter` parameter restricts which runs a scorer is eligible for, using a declarative predicate over the run's context. Filters are evaluated before sampling, so `sampling.rate` applies only to runs that match the filter:
+
+```typescript
+export const myAgent = new Agent({
+  // ...
+  scorers: {
+    relevancy: {
+      scorer: createAnswerRelevancyScorer({ model: 'openai/gpt-5-mini' }),
+      filter: {
+        op: 'eq',
+        left: { path: 'requestContext.plan' },
+        right: { literal: 'enterprise' },
+      },
+      sampling: { type: 'ratio', rate: 0.1 },
+    },
+  },
+})
+```
+
+This scores 10% of enterprise-plan traffic and none of the rest. To score different segments at different rates, bind the same scorer twice with complementary filters.
+
+Predicates can reference `requestContext.*`, `entity.*`, `entityType`, `source`, `threadId`, `resourceId`, and `projectId`. They support comparisons (`eq`, `ne`, `lt`, `lte`, `gt`, `gte`), membership (`in`, `notIn`), existence (`exists`, `notExists`), truthiness (`truthy`, `falsy`), and boolean composition (`and`, `or`, `not`). A filter that references an unknown root fails at agent construction rather than silently skipping scoring at runtime. Filters are plain JSON, so they're unaffected by durable agent state serialization.
+
+Eligibility filters decide _whether a scorer runs_; to filter _which messages a scorer sees_ once it runs, use [`filterRun()`](https://mastra.ai/reference/evals/filter-run).
+
 **Automatic storage**: All scoring results are automatically stored in the `mastra_scorers` table in your configured database, allowing you to analyze performance trends over time.
 
+## Score persistence
+
+Scores are persisted when the Mastra instance has `storage` configured, and when the scorer is registered on that instance. Registration is what lets Mastra resolve the scorer's metadata (name, description, type) through [`getScorerById()`](https://mastra.ai/reference/core/getScorerById) before writing the score.
+
+Scorers you attach to an agent or a workflow step register themselves. Scorers you pass directly to [`runEvals()`](https://mastra.ai/reference/evals/run-evals), including [Quick Checks](https://mastra.ai/docs/evals/quick-checks), need the `scorers` option on the [`Mastra` class](https://mastra.ai/reference/core/mastra-class):
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { LibSQLStore } from '@mastra/libsql'
+import { checks } from '@mastra/evals/checks'
+import { createAnswerRelevancyScorer } from '@mastra/evals/scorers/prebuilt'
+import { myAgent } from './agents/my-agent'
+
+export const mastra = new Mastra({
+  agents: { myAgent },
+  storage: new LibSQLStore({ url: 'file:./mastra.db' }),
+  scorers: {
+    calledTool: checks.calledTool('get_weather'),
+    includes: checks.includes('Brooklyn'),
+    relevancy: createAnswerRelevancyScorer({ model: 'openai/gpt-5-mini' }),
+  },
+})
+```
+
+The lookup only compares scorer IDs, so a registered instance can be configured differently from the one you evaluate with. Every `checks.calledTool()` instance has the id `check-called-tool`, so registering one covers all of them, whatever tool name you evaluate with.
+
+The arguments still shape the `description` stored alongside each score, which comes from the registered instance, not the one you evaluate with. `checks.calledTool('')` is accepted and persists scores fine, but stores `Checks that "" was called`, so pass a representative value.
+
+Skipping registration doesn't change scoring results, but each save fails with a `Scorer with id <id> not found` warning and the scores never reach the store.
+
 ## Trace evaluations
 
 In addition to live evaluations, you can use scorers to evaluate historical traces from your agent interactions and workflows.

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

@@ -241,7 +241,7 @@ await durableAgent.resume(runId, { approved: true })
 
 ## Crash recovery
 
-If the server process crashes while a durable agent run is in progress, that run remains in `running` status in storage with no automatic retry. On the next server start you can re-drive these orphaned runs so they pick up where they left off.
+If the server process crashes while a durable agent run is in progress, that run remains in `running` status in storage with no automatic retry. For orderly shutdowns such as rolling deploys, the generated server can also drain in-flight turns before exiting. See [graceful shutdown and rolling deploys](https://mastra.ai/docs/deployment/mastra-server). On the next server start you can re-drive these orphaned runs so they pick up where they left off.
 
 ### Automatic recovery
 

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

@@ -67,6 +67,8 @@ 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.
+
 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.
 
 ## Deploy to another environment
@@ -175,6 +177,105 @@ In CI, set `MASTRA_PROJECT_ID` and `MASTRA_API_TOKEN` and pass `--yes`:
 mastra deploy --env production --yes
 ```
 
+## Migrating from server and studio deploys
+
+`mastra server deploy` and `mastra studio deploy` are deprecated. They'll be removed in the next major version. Once removed, both commands will fail and legacy-pipeline projects can't deploy a new build until they migrate.
+
+Existing deployed services keep running. This only affects your ability to publish new deploys.
+
+### Who this affects
+
+You are on the legacy pipeline if any of these are true:
+
+- Your last deploy went out with `mastra server deploy` or `mastra studio deploy` and the deploy log printed a **Deprecated** banner.
+- Your project's most recent successful deploy used `@mastra/core` older than `1.44`.
+- Your organization hasn't been opted in to environment deploys.
+
+The deploy log is the source of truth: the legacy pipeline prints a deprecation banner on every deploy.
+
+### Migrate
+
+1. Upgrade `@mastra/core` in your project. The environment pipeline calls `setStudio` on the built artifact, which requires `@mastra/core` `>= 1.44`.
+
+   **npm**:
+
+   ```bash
+   npm install @mastra/core@latest
+   ```
+
+   **pnpm**:
+
+   ```bash
+   pnpm add @mastra/core@latest
+   ```
+
+   **Yarn**:
+
+   ```bash
+   yarn add @mastra/core@latest
+   ```
+
+   **Bun**:
+
+   ```bash
+   bun add @mastra/core@latest
+   ```
+
+   If you are jumping several minor versions, paste the following into a coding agent (Claude Code, Cursor, etc.) to catch breaking changes in APIs you actually use:
+
+   ```text
+   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:
+      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)
+         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 /
+         behavior change / none).
+      d. For each "breaks build" or "breaks runtime" row, implement the fix in my
+         codebase. For "behavior change" rows, leave a comment at the call site
+         explaining what changed so I can decide.
+      e. Bump `@mastra/core` (and any `@mastra/*` peers) to the latest matching
+         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
+      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
+   itself.
+   ```
+
+2. Replace the split command in your scripts and CI with the unified command:
+
+   ```diff
+   - mastra server deploy
+   - mastra studio deploy
+   + 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`.
+
+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.
+
+4. Move any project-level environment variables to the environment that needs them, in the dashboard under **Environments → \<env> → Variables**. See [Environment variables](https://mastra.ai/docs/mastra-platform/environments).
+
+### FAQ
+
+**My deploy fails with `MASTRA_CORE_TOO_OLD`.** The environment pipeline requires `@mastra/core` `>= 1.44`. Upgrade `@mastra/core` and redeploy.
+
+**My organization isn't opted in yet.** Contact support. Opt-in will be automatic before the next major version.
+
+**Can I roll back?** Yes. Environments retain deploy history and you can redeploy any prior successful artifact from the dashboard.
+
 ## Related
 
 - [Environments](https://mastra.ai/docs/mastra-platform/environments)

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

@@ -6,8 +6,6 @@ Server on Mastra platform is a production deployment target that runs your Mastr
 
 You get a stable API endpoint with environment variable management and custom domain support, plus deploy history out of the box.
 
-> **Note:** `mastra server deploy` is the earlier split deploy path. New projects should use the unified [`mastra deploy`](https://mastra.ai/docs/mastra-platform/deploy) command, which adds preflight validation, environments, and CLI-managed databases.
-
 > **Note:** Server deploy provisions hosted storage automatically. If you override storage with [LibSQLStore](https://mastra.ai/integrations/databases/libsql) and a file URL, switch to a remotely hosted database because Mastra platform uses an ephemeral filesystem.
 
 ## Quickstart
@@ -43,7 +41,7 @@ You get a stable API endpoint with environment variable management and custom do
 3. Deploy your project:
 
    ```bash
-   mastra server deploy
+   mastra deploy
    ```
 
    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.
@@ -157,7 +155,7 @@ Automate deployments from GitHub Actions, GitLab CI, or any CI provider. After y
 Pass `--yes` (or `-y`) to skip all confirmation prompts. Without it, the CLI waits for interactive input and your CI job hangs.
 
 ```bash
-mastra server deploy --yes
+mastra deploy --yes
 ```
 
 ### GitHub Actions
@@ -184,15 +182,13 @@ jobs:
       - name: Install dependencies
         run: npm install
       - name: Deploy to Mastra platform
-        run: npx mastra server deploy --yes
+        run: npx mastra deploy --yes
         env:
           MASTRA_API_TOKEN: ${{ secrets.MASTRA_API_TOKEN }}
 ```
 
 Adjust the `paths` filter and `working-directory` if your Mastra project is in a subdirectory (e.g. a monorepo).
 
-> **Note:** For Studio deploys, replace `mastra server deploy` with `mastra studio deploy`. The flags and environment variables are the same.
-
 ### GitLab CI
 
 The following pipeline deploys on pushes to `main`:
@@ -206,7 +202,7 @@ deploy:
   before_script:
     - npm install
   script:
-    - npx mastra server deploy --yes
+    - npx mastra deploy --yes
 ```
 
 Add `MASTRA_API_TOKEN` as a CI/CD variable in **Settings → CI/CD → Variables**.
@@ -217,7 +213,7 @@ Any CI system that runs Node.js and shell commands works with Mastra:
 
 1. Install dependencies.
 2. Set `MASTRA_API_TOKEN` as an environment variable.
-3. Run `mastra server deploy --yes` (or `mastra studio deploy --yes`).
+3. Run `mastra deploy --yes`.
 
 ### Verify the deploy
 
@@ -253,8 +249,7 @@ The CLI reads `organizationId` and `projectId` from `.mastra-project.json` by de
 
 ## Related
 
-- [`mastra server deploy`](https://mastra.ai/reference/cli/mastra)
+- [`mastra deploy`](https://mastra.ai/reference/cli/mastra)
 - [`mastra server pause`](https://mastra.ai/reference/cli/mastra)
 - [`mastra server restart`](https://mastra.ai/reference/cli/mastra)
-- [`mastra studio deploy`](https://mastra.ai/reference/cli/mastra)
 - [`mastra auth tokens`](https://mastra.ai/reference/cli/mastra)

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

@@ -6,8 +6,6 @@ Studio on Mastra platform is a hosted visual workspace for testing agents and ru
 
 You can deploy Studio from the CLI as shown below, or link a GitHub repository for push-to-deploy. See the [GitHub integration](https://mastra.ai/docs/mastra-platform/github) for the repository-linked flow.
 
-> **Note:** `mastra studio deploy` is the earlier split deploy path. New projects should use the unified [`mastra deploy`](https://mastra.ai/docs/mastra-platform/deploy) command, which adds preflight validation, environments, and CLI-managed databases.
-
 ## Quickstart
 
 1. Follow the [get started guide](https://mastra.ai/docs) to create your first Mastra project.
@@ -41,7 +39,7 @@ You can deploy Studio from the CLI as shown below, or link a GitHub repository f
 3. Deploy Studio with a single command:
 
    ```bash
-   mastra studio deploy
+   mastra deploy
    ```
 
    On a successful deploy, the CLI outputs the URL of your deployed Studio instance.
@@ -50,11 +48,11 @@ On your first deploy, the CLI prompts you to create a new project or select an e
 
 ## How deploy works
 
-The `mastra studio deploy` command builds your project and compiles `src/mastra/` into `.mastra/output`. It packages that output as an artifact ZIP, then uploads and deploys it to a cloud sandbox.
+The `mastra deploy` command builds your project and compiles `src/mastra/` into `.mastra/output`. It packages that output as an artifact ZIP, then uploads and deploys it to a cloud sandbox.
 
 A deploy transitions through **queued → uploading → starting → running** or **failed** if something goes wrong. If a sandbox is already running for your project, the platform updates it in place with no downtime. Otherwise, it creates a fresh sandbox. Your instance URL is assigned per project slug and remains stable across deploys.
 
-See the [`mastra studio deploy` CLI reference](https://mastra.ai/reference/cli/mastra) for the full list of flags and CI/CD usage.
+See the [`mastra deploy` CLI reference](https://mastra.ai/reference/cli/mastra) for the full list of flags and CI/CD usage.
 
 ## Environment files
 
@@ -63,17 +61,17 @@ A local env file is optional. When a `.env` or `.env.*` file is present in the p
 When multiple env files are present, the CLI prompts you to pick one. To select non-interactively, pass `--env-file`:
 
 ```bash
-mastra studio deploy --env-file .env.production --yes
+mastra deploy --env-file .env.production --yes
 ```
 
-To run the same codebase across `production` and `staging`, use the unified [`mastra deploy --env`](https://mastra.ai/docs/mastra-platform/deploy) command instead. [Environments](https://mastra.ai/docs/mastra-platform/environments) replace the earlier pattern of one project per environment.
+To run the same codebase across `production` and `staging`, use [`mastra deploy --env`](https://mastra.ai/docs/mastra-platform/deploy). See [Environments](https://mastra.ai/docs/mastra-platform/environments) for the full model.
 
 ## Create a new project non-interactively
 
-`mastra studio 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:
+`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:
 
 ```bash
-mastra studio deploy --project "my-new-project" --yes
+mastra deploy --project "my-new-project" --yes
 ```
 
 Use this from CI or AI coding agents instead of `mastra studio projects create`, which is interactive only.
@@ -84,4 +82,4 @@ To deploy Studio on your own infrastructure, see [Studio deployment](https://mas
 
 ## Related
 
-- [`mastra studio deploy`](https://mastra.ai/reference/cli/mastra)
+- [`mastra deploy`](https://mastra.ai/reference/cli/mastra)

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

@@ -87,11 +87,12 @@ MastraStorageExporter automatically selects the optimal tracing strategy based o
 
 ### Available Strategies
 
-| Strategy               | Description                                               | Use Case                            |
-| ---------------------- | --------------------------------------------------------- | ----------------------------------- |
-| **realtime**           | Process each event immediately                            | Development, debugging, low traffic |
-| **batch-with-updates** | Buffer events and batch write with full lifecycle support | Low volume Production               |
-| **insert-only**        | Only process completed spans, ignore updates              | High volume Production              |
+| Strategy               | Description                                                                           | Use Case                                   |
+| ---------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------ |
+| **realtime**           | Process each event immediately                                                        | Development, debugging, low traffic        |
+| **batch-with-updates** | Buffer events and batch write with full lifecycle support                             | Low volume Production                      |
+| **insert-only**        | Only process completed spans, ignore updates                                          | High volume Production                     |
+| **event-sourced**      | Write one row when a span starts and another when it ends, then collapse them on read | High volume Production, in-progress traces |
 
 ### Strategy Configuration
 
@@ -99,7 +100,7 @@ MastraStorageExporter automatically selects the optimal tracing strategy based o
 new MastraStorageExporter({
   strategy: 'auto', // Default - let storage provider decide
   // or explicitly set:
-  // strategy: 'realtime' | 'batch-with-updates' | 'insert-only'
+  // strategy: 'realtime' | 'batch-with-updates' | 'insert-only' | 'event-sourced'
 
   // Batching configuration (applies to both batch-with-updates and insert-only)
   maxBatchSize: 1000, // Max spans per batch
@@ -116,14 +117,17 @@ If you set the strategy to `'auto'`, the `MastraStorageExporter` automatically s
 
 ### Providers with Observability Support
 
-| Storage Provider                                                      | Preferred Strategy | Supported Strategies            | Recommended Use                       |
-| --------------------------------------------------------------------- | ------------------ | ------------------------------- | ------------------------------------- |
-| **[ClickHouse](https://mastra.ai/integrations/databases/clickhouse)** | insert-only        | insert-only                     | Production (high-volume)              |
-| **[PostgreSQL](https://mastra.ai/integrations/databases/postgresql)** | batch-with-updates | batch-with-updates, insert-only | Production (low volume)               |
-| **[MSSQL](https://mastra.ai/integrations/databases/mssql)**           | batch-with-updates | batch-with-updates, insert-only | Production (low volume)               |
-| **[MongoDB](https://mastra.ai/integrations/databases/mongodb)**       | batch-with-updates | batch-with-updates, insert-only | Production (low volume)               |
-| **[OracleDB](https://mastra.ai/integrations/databases/oracledb)**     | batch-with-updates | batch-with-updates, insert-only | Production (low volume)               |
-| **[libSQL](https://mastra.ai/integrations/databases/libsql)**         | batch-with-updates | batch-with-updates, insert-only | Default storage, good for development |
+| Storage Provider                                                              | Preferred Strategy | Supported Strategies            | Recommended Use                       |
+| ----------------------------------------------------------------------------- | ------------------ | ------------------------------- | ------------------------------------- |
+| **[ClickHouse](https://mastra.ai/integrations/databases/clickhouse)**         | insert-only        | insert-only                     | Production (high-volume)              |
+| **[PostgresStore](https://mastra.ai/integrations/databases/postgresql)**      | batch-with-updates | batch-with-updates, insert-only | Production (low volume)               |
+| **[PostgresStoreVNext](https://mastra.ai/integrations/databases/postgresql)** | event-sourced      | event-sourced                   | Production (high-volume)              |
+| **[MSSQL](https://mastra.ai/integrations/databases/mssql)**                   | batch-with-updates | batch-with-updates, insert-only | Production (low volume)               |
+| **[MongoDB](https://mastra.ai/integrations/databases/mongodb)**               | batch-with-updates | batch-with-updates, insert-only | Production (low volume)               |
+| **[OracleDB](https://mastra.ai/integrations/databases/oracledb)**             | batch-with-updates | batch-with-updates, insert-only | Production (low volume)               |
+| **[libSQL](https://mastra.ai/integrations/databases/libsql)**                 | batch-with-updates | batch-with-updates, insert-only | Default storage, good for development |
+
+> **Note:** Under `insert-only`, only completed spans are persisted, and span start and update events are ignored. A trace therefore becomes visible in Studio only after its root span ends, and filtering traces by `status: 'running'` returns no results. `PostgresStoreVNext` uses `event-sourced` tracing instead, so in-progress traces remain visible while preserving append-only writes.
 
 ### Providers without Observability Support
 
@@ -141,6 +145,7 @@ The following storage providers **don't support** the observability domain. If y
 - **realtime**: Immediate visibility, best for debugging
 - **batch-with-updates**: 10-100x throughput improvement, full span lifecycle
 - **insert-only**: Additional 70% reduction in database operations, perfect for analytics
+- **event-sourced**: Append-only like insert-only, but in-progress traces stay visible in Studio while a run executes
 
 ## Production recommendations
 

package/.docs/docs/sandbox/filesystem.md

@@ -7,7 +7,7 @@ A filesystem gives an agent tools for reading, writing, listing, and [searching]
 Configure files in two ways:
 
 - [Direct filesystem access](#direct-filesystem-access) uses `filesystem` with one filesystem provider or a [`CompositeFilesystem`](#manual-composition) that you create yourself.
-- [Mounts](#mounts) uses `mounts` to create a `CompositeFilesystem` from path-prefixed providers. When the workspace also has a static sandbox, Mastra attempts to mount each provider at its configured path inside the sandbox so commands can access the same files. Remote sandbox mounts typically use Filesystem in Userspace (FUSE).
+- [Mounts](#mounts) uses `mounts` to create a `CompositeFilesystem` from path-prefixed providers. When a static sandbox and filesystem provider support mounting, Mastra automatically mounts the provider at its configured path. Remote sandbox mounts typically use Filesystem in Userspace (FUSE).
 
 Configure either `filesystem` or `mounts`, not both. Configuring both throws a `WorkspaceError` with the code `INVALID_CONFIG`.
 
@@ -71,7 +71,7 @@ See [Search](https://mastra.ai/docs/sandbox/search) to index the files for keywo
 
 ## Mounts
 
-Use `mounts` when programs inside a sandbox need to access persistent files by path. The agent still receives file tools, while command tools can run commands such as `ls`, `cat`, or `python` against the same files.
+Use `mounts` when programs inside a sandbox need to access persistent files by path. Mastra creates the mount automatically when the sandbox and filesystem provider support it. The agent still receives file tools, while command tools can run commands such as `ls`, `cat`, or `python` against the same files.
 
 For example, mount an S3 bucket at `/workspace` inside a Daytona sandbox:
 
@@ -180,7 +180,7 @@ Use manual composition when another part of your application needs the composite
 
 ## Mount availability
 
-File tools and composite routing work without FUSE. Remote sandboxes can use FUSE to make cloud storage visible to commands. `LocalSandbox` uses symlinks instead.
+File tools and composite routing work without a sandbox mount. When a remote sandbox and filesystem provider support mounting, `mounts` automatically uses FUSE to make the files visible to commands. `LocalSandbox` uses symlinks instead.
 
 Built-in sandbox mounting currently includes:
 
@@ -195,27 +195,27 @@ Remote mounts may require `s3fs`, `gcsfuse`, or `blobfuse2` inside the sandbox.
 
 If a sandbox mount is unavailable or fails, the workspace remains usable. File tools continue to access the provider through its SDK, but commands can't see that path. Mastra describes these providers to the agent as available through file tools only.
 
-## Multi-tenant filesystems
+## Filesystems per user or thread
 
 The `filesystem` option accepts a resolver when storage should vary by request, user, role, or tenant:
 
 ```typescript
 const workspace = new Workspace({
   filesystem: ({ requestContext }) => {
-    const tenantId = requestContext.get('tenant-id') as string
+    const userId = requestContext.get('user-id') as string
 
     return new S3Filesystem({
       bucket: process.env.S3_BUCKET!,
       region: process.env.S3_REGION!,
-      prefix: `tenants/${tenantId}`,
+      prefix: `users/${userId}`,
     })
   },
 })
 ```
 
-Each tenant gets its own filesystem view, and file tools resolve the provider from the request context automatically.
+Each user gets a separate filesystem view, and file tools resolve the provider from the request context automatically.
 
-`mounts` doesn't accept a resolver and can't be combined with a sandbox resolver. When each user or thread needs separate storage inside a separate sandbox, create and mount the provider inside the sandbox resolver. See [Multi-tenant sandboxes](https://mastra.ai/docs/sandbox/overview).
+`mounts` doesn't accept a resolver and can't be combined with a sandbox resolver. When each user or thread needs separate storage inside a separate sandbox, create and mount the provider inside the sandbox resolver. See [Sandboxes per user or thread](https://mastra.ai/docs/sandbox/overview).
 
 ## Policies and containment