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

package/.docs/docs/channels.md

@@ -82,7 +82,7 @@ For example, a Slack adapter on an agent with the `your-agent` ID uses:
 /api/agents/your-agent/channels/slack/webhook
 ```
 
-Point the platform's webhook, event, or interactions URL to this path. Follow the guide for your platform or the [Chat SDK docs](https://chat-sdk.dev/adapters).
+Point the platform's webhook, event, or interactions URL to this path. Follow the guide for your platform or the [Chat SDK docs](https://chat-sdk.dev/adapters). The webhook acknowledges the request before the agent finishes responding. See [Error handling and delivery](#error-handling-and-delivery) for what happens when verification or a handler fails.
 
 During local development, platform webhooks need a public URL to reach your local server. Use a tunnel like [cloudflared](https://github.com/cloudflare/cloudflared) or [ngrok](https://ngrok.com/) to expose your server, `localhost:4111` by default:
 
@@ -215,6 +215,32 @@ Add only JSON-serializable, non-sensitive values. Signal metadata may be stored
 
 Use `requestContext` for run-scoped configuration, such as credentials for a message that starts a run. Use `signalMetadata` for context that must stay attached to one message, including messages delivered to an active run.
 
+## Error handling and delivery
+
+A channel webhook acknowledges the platform before the agent finishes, so a `200` response means "received", not "answered". Before that acknowledgment, the adapter rejects bad requests synchronously (`401` for failed verification, `400` for an unparseable body, `503` for transient state failures) and the platform redelivers on non-`2xx` responses per its own policy. After the `200`, the platform never retries and Mastra owns errors. The default handler catches agent-run failures and posts an error message to the thread (customize it with `formatError`, which defaults to `❌ Error: {message}`). A custom handler that throws is only logged by Chat SDK, so nothing is posted or retried. Catch failures in custom handlers yourself:
+
+```typescript
+channels: {
+  adapters: {
+    slack: createSlackAdapter(),
+  },
+  handlers: {
+    onDirectMessage: async (thread, message, defaultHandler, ctx) => {
+      try {
+        ctx.signalMetadata.ticketId = await lookupTicket(message)
+      } catch (error) {
+        ctx.mastra?.getLogger().error('Ticket lookup failed', { error })
+        await thread.post('Something went wrong looking up your ticket. Try again in a moment.')
+        return
+      }
+      await defaultHandler(thread, message)
+    },
+  },
+},
+```
+
+Platform retries also mean the same event can arrive more than once. Adapters deduplicate redelivered events using channel state, so configure [storage](https://mastra.ai/docs/storage) to keep deduplication reliable across restarts. Deduplication is best effort, so keep side effects in custom handlers idempotent so a duplicate that slips through doesn't repeat work like creating a ticket.
+
 ## Multimodal content
 
 Models like Gemini can process images, video, and audio natively. Combine `inlineMedia` and `inlineLinks` to let users share rich content with your agent across platforms:
@@ -327,6 +353,7 @@ At the time of writing, Chat SDK lists adapters for:
 - Kapso
 - Lark / Feishu
 - Linear
+- Linq
 - Liveblocks
 - Matrix
 - Mattermost

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

@@ -20,6 +20,7 @@ The following pages show you how to deploy Mastra to specific cloud providers.
 - [Digital Ocean](https://mastra.ai/integrations/deploy/digital-ocean)
 - [Inngest](https://mastra.ai/integrations/deploy/inngest)
 - [Kubernetes](https://mastra.ai/integrations/deploy/kubernetes)
+- [Kubernetes (Helm)](https://mastra.ai/integrations/deploy/kubernetes-helm)
 - [Netlify](https://mastra.ai/integrations/deploy/netlify)
 - [Render](https://mastra.ai/integrations/deploy/render)
 - [Temporal](https://mastra.ai/integrations/deploy/temporal)

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/overview.md

@@ -51,6 +51,7 @@ Use this option for auto-scaling, minimal infrastructure management, or when you
 - [Digital Ocean](https://mastra.ai/integrations/deploy/digital-ocean)
 - [Inngest](https://mastra.ai/integrations/deploy/inngest)
 - [Kubernetes](https://mastra.ai/integrations/deploy/kubernetes)
+- [Kubernetes (Helm)](https://mastra.ai/integrations/deploy/kubernetes-helm)
 - [Netlify](https://mastra.ai/integrations/deploy/netlify)
 - [Render](https://mastra.ai/integrations/deploy/render)
 - [Temporal](https://mastra.ai/integrations/deploy/temporal)

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/overview.md

@@ -115,13 +115,45 @@ 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

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/api.md

@@ -105,6 +105,60 @@ The root URL for the endpoints below is: `/v1/gateway`
 | GET    | `/projects/:id/memory/threads/:threadId/observations/history` | Observation history (dashboard)             |
 | GET    | `/models`                                                     | List available models                       |
 
+## Observability feedback query API
+
+The hosted feedback query API lists and analyzes feedback exported to Mastra Platform Observability. Because the API is unversioned, backwards compatibility isn't guaranteed. Rate limits, retention, and ingestion-to-query freshness aren't published contracts.
+
+Use the root URL for your environment's data-residency region:
+
+| Region         | Root URL                                               |
+| -------------- | ------------------------------------------------------ |
+| United States  | `https://observability.mastra.ai/api/observability`    |
+| European Union | `https://observability.eu.mastra.ai/api/observability` |
+
+Telemetry stays in its residency region. Querying the other region returns no records for the environment. See [Observability co-location](https://mastra.ai/docs/mastra-platform/regions) for the environment-to-region mapping.
+
+### Authentication and project scope
+
+Every request requires a platform access token. Create one in [Mastra Platform](https://projects.mastra.ai), or use the token written to `.env` during Platform setup.
+
+Include `X-Mastra-Project-Id` to limit results to one project. If you omit it, the query covers feedback in every project available to the token's organization.
+
+```bash
+curl -sS "https://observability.mastra.ai/api/observability/feedback?page=0&perPage=20&feedbackType=rating" \
+  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
+  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq
+```
+
+Use an organization-scoped Platform access token. Gateway inference keys such as `mk_*` keys aren't accepted. Queries remain constrained to the token's organization even when you supply a project ID.
+
+### Endpoints
+
+| Method | Endpoint                | Description                  |
+| ------ | ----------------------- | ---------------------------- |
+| GET    | `/feedback`             | List feedback records        |
+| POST   | `/feedback/aggregate`   | Return one aggregate value   |
+| POST   | `/feedback/breakdown`   | Group feedback by dimensions |
+| POST   | `/feedback/timeseries`  | Bucket feedback by interval  |
+| POST   | `/feedback/percentiles` | Return percentile series     |
+
+The list endpoint accepts page-mode parameters such as `page`, `perPage`, `field`, and `direction`, plus feedback filters as query parameters. It also supports delta polling with `mode=delta`, `after`, and `limit`. Responses contain a `feedback` array and page or delta metadata.
+
+Analytics endpoints accept the same JSON request shapes and return types as the [feedback reference](https://mastra.ai/reference/observability/feedback). Analytics operate only on numeric feedback values.
+
+```bash
+curl -sS "https://observability.mastra.ai/api/observability/feedback/aggregate" \
+  -X POST \
+  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
+  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" \
+  -H "Content-Type: application/json" \
+  --data '{"feedbackType":"rating","feedbackSource":"user","aggregation":"avg"}' | jq
+```
+
+The API returns `401` for invalid credentials, `403` for organization authorization failures, and `400` for malformed query arguments or JSON bodies.
+
+Hosted observability doesn't provide a feedback creation route. Export feedback from the application as described in [Export feedback to Mastra Platform](https://mastra.ai/docs/observability/feedback).
+
 ## Gateway proxy endpoints
 
 Visit the [Gateway documentation](https://gateway.mastra.ai/docs) for more details.

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/observability.md

@@ -130,7 +130,7 @@ See [Mastra storage exporter](https://mastra.ai/docs/observability/integrations/
 
 ## View observability data
 
-Open your project in [Mastra Platform](https://projects.mastra.ai) to inspect exported traces, logs, metrics, scores, and feedback. A Studio or Server deployment isn't required.
+Open your project in [Mastra Platform](https://projects.mastra.ai) to inspect exported traces, logs, metrics, and scores. A Studio or Server deployment isn't required. Query exported feedback through the hosted feedback API described below.
 
 Use a consistent `serviceName` to filter data from a specific application or deployment.
 
@@ -164,6 +164,8 @@ bun x mastra api trace list
 
 The CLI can infer platform credentials from your project environment. See the [`mastra api` CLI reference](https://mastra.ai/reference/cli/mastra) for available commands, filtering, pagination, credential resolution, and `curl` examples.
 
+You can query exported feedback over HTTP. See the [observability feedback query API](https://mastra.ai/docs/mastra-platform/api) for its current status, regional endpoints, authentication, and project scoping.
+
 ## Next steps
 
 - 📹 [Mastra observability and Studio workshop](https://www.youtube.com/watch?v=dKO_a3RPra0)

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/memory/semantic-recall.md

@@ -350,6 +350,25 @@ const agent = new Agent({
 })
 ```
 
+FastEmbed also exposes the multilingual E5 model for non-English content. E5 is asymmetric, so it's exposed as two models: `multilingualE5LargePassage` for text you index and `multilingualE5LargeQuery` for search text.
+
+```ts
+import { Memory } from '@mastra/memory'
+import { Agent } from '@mastra/core/agent'
+import { fastembed } from '@mastra/fastembed'
+
+const agent = new Agent({
+  id: 'agent',
+  memory: new Memory({
+    embedder: fastembed.multilingualE5LargePassage,
+  }),
+})
+```
+
+Memory uses a single embedder for both storing and recalling messages, so pick one of the two models and use it consistently. Use the paired `multilingualE5LargeQuery` model only where you control both sides of the pipeline, such as a RAG workflow that indexes with the passage model and searches with the query model.
+
+Multilingual E5 produces 1024-dimensional vectors. Your vector index must be created with matching dimensions, and E5 vectors can't be mixed with vectors from another embedder in the same index.
+
 ## PostgreSQL index optimization
 
 When using PostgreSQL as your vector store, you can optimize semantic recall performance by configuring the vector index. This is particularly important for large-scale deployments with thousands of messages.

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

@@ -33,6 +33,10 @@ await mastra.observability.addFeedback({
 })
 ```
 
+When you pass only `traceId` and `spanId`, `addFeedback()` rehydrates the target from configured observability storage before emitting the feedback event. Configure [`MastraStorageExporter`](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage) when feedback is added after the traced execution has finished. If the trace isn't available in storage, Mastra logs a warning and drops the feedback event.
+
+During a live traced execution, you can pass its `correlationContext` to emit feedback without rehydrating the trace from storage. This path is useful when the active request collects feedback before its tracing context ends.
+
 ## Find the trace for a message
 
 Feedback is usually collected against a message a user has already read, so you need the `traceId` for that message. Assistant messages carry it in `content.metadata`, both in the stream result and when the message is recalled later from memory:
@@ -143,6 +147,16 @@ const ratingsOverTime = await observability!.getFeedbackTimeSeries({
 
 See the [feedback reference](https://mastra.ai/reference/observability/feedback) for all fields, filters, return types, and percentile query parameters.
 
+The local runtime exposes the list route at `/api/observability/feedback` and analytics under its related paths. See the [HTTP routes table](https://mastra.ai/reference/observability/feedback). Mastra Platform provides a separate, unversioned hosted query API. See the [observability feedback query API](https://mastra.ai/docs/mastra-platform/api) for regional endpoints, authentication, and project scoping.
+
+## Export feedback to Mastra Platform
+
+[`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.
+
+See [Observability on Mastra Platform](https://mastra.ai/docs/mastra-platform/observability) for the combined exporter configuration.
+
 ## Export feedback to external platforms
 
 Feedback flows through the observability event bus, so exporters that support feedback forward it automatically. The [PostHog exporter](https://mastra.ai/reference/observability/tracing/exporters/posthog) sends feedback as native `$ai_feedback` events that appear on the linked trace in PostHog.

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