@mastra/mcp-docs-server 1.2.8-alpha.2 → 1.2.8-alpha.23

package/.docs/docs/index.md

@@ -44,17 +44,31 @@ export const weatherTool = createTool({
     location: z.string().describe('City name'),
   }),
   outputSchema: z.object({
-    output: z.string(),
+    location: z.string(),
+    temperatureCelsius: z.number(),
+    conditions: z.string(),
   }),
   execute: async ({ location }) => {
     return {
-      output: `The weather in ${location} is sunny`,
+      location,
+      temperatureCelsius: 21,
+      conditions: 'sunny',
     }
   },
 })
 ```
 
-If you need to create an agent, create a new file and use `import { Agent } from "@mastra/core/agent"`. The constructor takes `{ id, name, instructions, model }`. The `model` property is a string in Mastra's model router format: `provider/model`, for example `openai/gpt-5.5`. For OpenAI models, use `openai/<model>`, not `openai:<model>`, and don't pass a provider object. No provider import is needed for this format. Don't install any AI SDK package unless Mastra's documentation says otherwise.
+If you need to create an agent, create a new file and use `import { Agent } from "@mastra/core/agent"`. The constructor takes `{ id, name, instructions, model }`. The `model` property is a string in Mastra's model router format. No provider import is needed for this format. Don't install any AI SDK package unless Mastra's documentation says otherwise.
+
+By defining the model using `provider/model` format Mastra automatically looks for environment variables for the given provider. The defined model requires an environment variable to be set for the provider. OpenAI: `OPENAI_API_KEY`. Anthropic: `ANTHROPIC_API_KEY`. Google: `GOOGLE_API_KEY`. Example: Any `openai/<model>` requires the `OPENAI_API_KEY` environment variable. Go to <https://mastra.ai/models/environment-variables> for a full list of supported providers and their environment variable names.
+
+Short list of known model IDs are:
+
+- `openai/gpt-5.5`, `openai/gpt-5-mini`
+- `anthropic/claude-sonnet-4-6`, `anthropic/claude-opus-4-7`, `anthropic/claude-haiku-4-5`
+- `google/gemini-2.5-flash`
+
+Go to <https://mastra.ai/models> for a full list of supported models.
 
 Add a tool an agent by importing the tool and passing it to the agent constructor as a tools object.
 
@@ -83,16 +97,6 @@ export const weatherAgent = new Agent({
 })
 ```
 
-By defining the model using `provider/model` format Mastra automatically looks for environment variables for the given provider. The defined model requires an environment variable to be set for the provider. OpenAI: `OPENAI_API_KEY`. Anthropic: `ANTHROPIC_API_KEY`. Google: `GOOGLE_API_KEY`. Example: Any `openai/<model>` requires the `OPENAI_API_KEY` environment variable. Go to <https://mastra.ai/models/environment-variables> for a full list of supported providers and their environment variable names.
-
-Short list of known model IDs are:
-
-- `openai/gpt-5.5`, `openai/gpt-5-mini`
-- `anthropic/claude-sonnet-4-6`, `anthropic/claude-opus-4-7`, `anthropic/claude-haiku-4-5`
-- `google/gemini-2.5-flash`
-
-Go to <https://mastra.ai/models> for a full list of supported models.
-
 Create a Mastra entry point at `src/mastra/index.ts` and register the agent:
 
 ```ts

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

@@ -66,8 +66,8 @@ export const researchTool = createTool({
     timeoutMs: 600_000,
     maxRetries: 1,
   },
-  execute: async ({ context }) => {
-    // ...
+  execute: async ({ topic }) => {
+    // Run the research job for topic
   },
 })
 ```

package/.docs/docs/long-running-agents/durable-agents.md

@@ -159,8 +159,9 @@ cleanup()
 ```typescript
 import { createDurableAgent } from '@mastra/core/agent/durable'
 import { RedisServerCache } from '@mastra/redis'
+import Redis from 'ioredis'
 
-const cache = new RedisServerCache({ url: 'redis://localhost:6379' })
+const cache = new RedisServerCache({ client: new Redis('redis://localhost:6379') })
 
 export const durableAgent = createDurableAgent({
   agent,

package/.docs/docs/long-running-agents/goals.md

@@ -59,7 +59,7 @@ A goal step runs inside the agentic execution loop, right after `isTaskComplete`
 
 - **Not satisfied, budget remaining** → the loop continues; per-evaluation feedback is injected so the agent iterates.
 - **Satisfied** → the loop stops and the objective is marked `done`.
-- **Budget exhausted** (`runsUsed >= maxRuns`) → the loop stops but the objective stays `active`, so raising `maxRuns` later can resume it.
+- **Budget exhausted** (`runsUsed >= maxRuns`) → the loop stops and the objective is marked `paused`. Raise `maxRuns`, then resume the objective to continue.
 
 The step is a no-op for background-task, mid-tool-loop, and working-memory-only iterations — the same gating as `isTaskComplete`.
 
@@ -103,6 +103,8 @@ await worker.updateObjectiveOptions({ threadId, maxRuns: 100 })
 await worker.clearObjective({ threadId })
 ```
 
+Objective records include an optional `activeDurationMs` value for user interfaces that display active pursuit time. Mastra advances this value while an agent runs toward an active objective and checkpoints it when the run ends or waits for tool approval. Missing values represent zero, and the duration measures agent execution rather than the goal's wall-clock age.
+
 Per-objective values written by `setObjective` / `updateObjectiveOptions` take precedence over the agent's `goal` config, and that precedence is remembered in thread state. See the [`GoalEvaluationPayload` in the ChunkType reference](https://mastra.ai/reference/streaming/ChunkType) for the full goal chunk shape.
 
 ## Related

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

@@ -34,8 +34,8 @@ For most agent-focused projects, **Turso** is the simplest starting point. It pr
 
 A database is attached at one of two scopes:
 
-- **Project scope**: The default. One database shared by all of the project's [environments](https://mastra.ai/docs/mastra-platform/environments). Its variables are injected into every deploy.
-- **Environment scope**: Attached to a single environment. Use this to isolate data between environments, for example separate production and staging databases.
+- **Environment scope**: The default. Attached to a single environment so data stays isolated between environments (for example separate production and staging databases). When your project has one environment, `mastra env db create` picks it automatically; with several, the CLI prompts you to select one.
+- **Project scope**: One database shared by all of the project's [environments](https://mastra.ai/docs/mastra-platform/environments). Opt in with `--shared`. Its variables are injected into every deploy.
 
 The scope is set when you attach the database and shown in `mastra env db list`.
 
@@ -43,22 +43,28 @@ The two scopes can't overlap for the same provider. Because a project-scoped dat
 
 ## Attach with the CLI
 
-Create and attach a database in one command. The CLI polls until it's ready, which takes a few seconds:
+You don't have to run this command up front. If your project needs a hosted database but doesn't have one yet, `mastra deploy` offers to attach one for you when the deploy preflight check runs. Say yes and the deploy continues without leaving the CLI.
+
+Alternatively, create and attach a database ahead of time. The CLI polls until it's ready, which takes a few seconds:
 
 ```bash
-# Shared by all environments
+# Scoped to a single environment (the CLI picks the only one, or prompts if there are several)
 mastra env db create --kind turso
 
-# Scoped to the staging environment
+# Scoped to a specific environment
 mastra env db create staging --kind turso
+
+# Shared by all environments
+mastra env db create --kind turso --shared
 ```
 
 Supported kinds are `turso` and `neon` (Postgres). Useful flags:
 
+- `--shared`: Attach a project-scoped database shared by every environment. Cannot be combined with an environment argument.
 - `--name <name>`: Database name. Defaults to a name derived from the project slug.
 - `--region <region>`: Provider region ID for project-scoped databases (for example `fra`). Environment-scoped databases are placed near the environment's region automatically, and an explicit `--region` is ignored.
 - `--no-wait`: Return immediately instead of polling. Check progress later with `mastra env db show`.
-- `--json`: Machine-readable output.
+- `--json`: Machine-readable output. When the project has multiple environments, `--json` requires an environment argument or `--shared` (no interactive prompt).
 
 Inspect and manage attached databases:
 

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

@@ -26,21 +26,27 @@ A local `.env` file is optional. Environment variables stored on the platform ar
 
    On the first run the CLI prompts you to create the platform project (named after your `package.json`) and the `production` environment. Accept the prompts, or pass `--yes` to accept defaults without confirmation.
 
-2. The CLI runs a preflight check before anything ships. Storage that would fall back to a local file path blocks the deploy, because local files don't survive on the platform's ephemeral filesystem:
+2. The CLI runs a preflight check before anything ships. Storage that would fall back to a local file path (which doesn't survive on the platform's ephemeral filesystem) would normally block the deploy:
 
    ```text
-   [LOCAL_STORAGE_PATH] file:./mastra.db will be used at runtime because TURSO_DATABASE_URL is not set
+   file:./mastra.db will be used at runtime because TURSO_DATABASE_URL is not set
    ```
 
-   Attach a [hosted database](https://mastra.ai/docs/mastra-platform/database) that provides the missing variables:
+   Instead of erroring out, the CLI offers to fix it inline for you:
+
+   ```text
+   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.
 
    ```bash
-   mastra env db create --kind turso
+   mastra env db create production --kind turso
    ```
 
-   Provisioning takes a few seconds. The database's connection variables are injected into your deploys automatically, with nothing to copy into an `.env` file.
+   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.
 
-   > **Note:** If preflight reports a hard-coded local path instead (`Build contains a host-local storage URL`), guard it 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({
@@ -77,7 +83,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.
+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.
 
 ## Preflight checks
 
@@ -139,6 +145,7 @@ mastra deploy --env production --yes
 ## Related
 
 - [Environments](https://mastra.ai/docs/mastra-platform/environments)
+- [Regions](https://mastra.ai/docs/mastra-platform/regions)
 - [Hosted databases](https://mastra.ai/docs/mastra-platform/database)
 - [`mastra deploy` CLI reference](https://mastra.ai/reference/cli/mastra)
 - [Configuration](https://mastra.ai/docs/mastra-platform/configuration)

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

@@ -26,7 +26,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. 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. 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.
 
 ## List environments
 
@@ -77,16 +77,16 @@ Each row shows the deploy status, environment, timestamp, and which deploy is cu
 
 ## Isolate an environment's data
 
-By default a hosted database attached to the project is shared by all environments. To isolate production data from staging data, attach a separate database to each environment instead:
+Hosted databases are scoped to a single environment by default, so production and staging each read and write their own database:
 
 ```bash
 mastra env db create production --kind turso --name my-project-production-db
 mastra env db create staging --kind turso --name my-project-staging-db
 ```
 
-Each environment then reads and writes only its own database.
+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 project-scoped 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.
+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.
 
 ## Delete an environment
 
@@ -99,5 +99,6 @@ The CLI asks for confirmation before deleting. Deleting an environment removes i
 ## Related
 
 - [Deploy](https://mastra.ai/docs/mastra-platform/deploy)
+- [Regions](https://mastra.ai/docs/mastra-platform/regions)
 - [Hosted databases](https://mastra.ai/docs/mastra-platform/database)
 - [`mastra env` CLI reference](https://mastra.ai/reference/cli/mastra)

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

@@ -4,15 +4,15 @@
 
 Observability on Mastra platform is a standalone hosted product for searchable traces, logs, and metrics across Mastra projects and deploys. Use it when you want observability without deploying Studio first or setting up local storage.
 
-Mastra can configure platform observability during project setup. The CLI provisions a platform project, writes the required environment variables, and registers observability exporters in your Mastra config.
+Use `mastra init` to configure platform observability while adding Mastra to an existing application, or configure it manually in a newly created Mastra project.
 
 ## Quickstart
 
-Choose the setup path that matches your project. New and existing projects can use the CLI to provision Observability automatically, while manual setup is available when you already manage platform projects and environment variables yourself.
+Choose the setup path that matches your project.
 
 ### New project
 
-Create a new Mastra project:
+Create a managed Mastra project. When prompted, opt into Mastra Platform Observability to configure it automatically:
 
 **npm**:
 
@@ -38,15 +38,7 @@ yarn create mastra
 bunx create-mastra
 ```
 
-When prompted, enable Mastra Observability:
-
-```bash
-Enable Mastra Observability? (will open auth flow)
-
-> Yes
-```
-
-The CLI authenticates with Mastra platform, creates a platform project, writes the required environment variables, and configures the observability exporters.
+When you select observability, the create command authenticates with Mastra Platform, provisions a platform project, and writes the credentials to your project. If you skip platform setup or use a prompt-free creation flow, follow the [manual setup](#manual-setup) steps instead.
 
 ### Existing non-Mastra projects
 

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

@@ -10,7 +10,7 @@ The [Mastra platform](https://projects.mastra.ai) provides three products for de
 
 Deploy with a single command, [`mastra deploy`](https://mastra.ai/docs/mastra-platform/deploy), or connect a GitHub repository for push-to-deploy. See the [GitHub integration](https://mastra.ai/docs/mastra-platform/github) for the repository-linked flow.
 
-Each project can run multiple [**Environments**](https://mastra.ai/docs/mastra-platform/environments) (for example `production` and `staging`) and provision [**Hosted databases**](https://mastra.ai/docs/mastra-platform/database) from the CLI or project settings to persist application data with no manual configuration.
+Each project can run multiple [**Environments**](https://mastra.ai/docs/mastra-platform/environments) (for example `production` and `staging`), provision [**Hosted databases**](https://mastra.ai/docs/mastra-platform/database) from the CLI or project settings to persist application data, and get a managed [**Workspace**](https://mastra.ai/docs/mastra-platform/workspace) per environment that gives agents a filesystem and a sandbox with no manual configuration.
 
 ## Get started
 

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

@@ -0,0 +1,73 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Regions
+
+A region controls where a platform environment runs, where its [hosted database](https://mastra.ai/docs/mastra-platform/database) is placed, and where its observability data is stored. The region is fixed when the environment is created and can't be changed later.
+
+Mastra platform offers two residency zones today, `us` and `eu`, backed by specific compute regions on Railway. Databases and observability follow the environment's region automatically.
+
+## Choose a region
+
+Pass `--region` when creating or first deploying to an environment:
+
+```bash
+mastra deploy --env production --region eu
+mastra env create staging --region us
+```
+
+Both `mastra deploy --region` and `mastra env create --region` accept either the `us` / `eu` shorthand or a canonical Railway region code from the table below. Shorthand is the recommended form.
+
+The default when no region is passed is `us`, which resolves to `pdx` (Portland, Oregon).
+
+## Available regions
+
+The residency selector offers four Railway regions across two zones. `us` and `eu` shorthand resolve to the underlined default in each zone.
+
+| Zone | Railway code    | Location                  |
+| ---- | --------------- | ------------------------- |
+| `us` | `pdx` (default) | Portland, Oregon          |
+| `us` | `iad`           | Ashburn, Virginia         |
+| `us` | `sfo`           | San Francisco, California |
+| `eu` | `ams` (default) | Amsterdam, Netherlands    |
+
+Pass a Railway code directly when you need to pin an environment to a specific data center. Passing `us` selects `pdx`, and passing `eu` selects `ams`.
+
+> **Note:** Additional Railway regions exist in the deploy pipeline (for example Singapore, `sin`) but aren't offered in the residency selector yet, because hosted databases and observability don't have local placement outside the US and EU. Passing an unrecognized region falls back to the US default rather than pinning to it.
+
+## Hosted database placement
+
+When you attach an [environment-scoped database](https://mastra.ai/docs/mastra-platform/database), the platform picks the provider region closest to the environment. This is server-authoritative, so an explicit `--region` on `mastra env db create <env>` is ignored. The environment's region is the source of truth.
+
+| Environment region | Turso region      | Postgres (Neon) region         |
+| ------------------ | ----------------- | ------------------------------ |
+| `pdx`              | `sjc` (San Jose)  | `aws-us-west-2` (Oregon)       |
+| `iad`              | `iad` (Ashburn)   | `aws-us-east-1` (N. Virginia)  |
+| `sfo`              | `sjc` (San Jose)  | `aws-us-west-2` (Oregon)       |
+| `ams`              | `ams` (Amsterdam) | `aws-eu-central-1` (Frankfurt) |
+
+Project-scoped databases (shared across environments) accept an explicit `--region` because they aren't bound to a single environment. Use a provider region ID for the flag, not the `us` / `eu` shorthand:
+
+```bash
+mastra env db create --kind turso --region fra
+mastra env db create --kind neon --region aws-us-east-1
+```
+
+Turso offers 20+ regions and Postgres (Neon) is available across AWS and Azure regions in the US, EU, and APAC. See the [Turso regions list](https://docs.turso.tech/features/data-edge#locations) and [Neon regions list](https://neon.com/docs/introduction/regions) for the full set. Passing a code not offered by the provider fails at attach time with the provider's error.
+
+## Observability co-location
+
+Observability ingest runs in two regions today: **US** (Iowa, `us-central1`) and **EU** (Amsterdam). Every environment's traces, logs, and metrics are routed to the ingest region that matches its residency zone:
+
+| Environment region                  | Observability region |
+| ----------------------------------- | -------------------- |
+| `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.
+
+## Related
+
+- [Deploy](https://mastra.ai/docs/mastra-platform/deploy)
+- [Environments](https://mastra.ai/docs/mastra-platform/environments)
+- [Hosted databases](https://mastra.ai/docs/mastra-platform/database)
+- [Observability](https://mastra.ai/docs/mastra-platform/observability)

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

@@ -0,0 +1,111 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Workspace
+
+A workspace gives an environment two things your agents can use at runtime:
+
+- A **bucket** for filesystem storage, exposed to your code as [`PlatformFilesystem`](https://mastra.ai/reference/workspace/platform-filesystem).
+- A **sandbox** for executing commands, exposed as [`PlatformSandbox`](https://mastra.ai/reference/workspace/platform-sandbox).
+
+Workspaces are provisioned per [environment](https://mastra.ai/docs/mastra-platform/environments), so `production` and `staging` each get their own bucket and sandbox. The platform manages provisioning, credentials, and lifecycle; your deploy code only needs to construct the providers.
+
+## When workspaces are provisioned
+
+New projects have workspaces enabled by default. When you create an environment, the platform provisions a bucket for it automatically. The sandbox base image is warmed in the background so the first `PlatformSandbox` call starts quickly.
+
+Existing projects that haven't opted in show an **Enable workspaces** action in the Workspaces tab. Enabling provisions a bucket for every environment on the project.
+
+If provisioning fails for an environment — for example while Railway is under load — the Workspaces tab shows the failure and offers a retry. The environment itself is still created; only the workspace is unavailable until you retry.
+
+## Use the workspace from your code
+
+Install the provider package:
+
+**npm**:
+
+```bash
+npm install @mastra/platform-workspace
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/platform-workspace
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/platform-workspace
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/platform-workspace
+```
+
+Compose the providers into a workspace and register it with Mastra:
+
+```typescript
+import { Workspace } from '@mastra/core/workspace'
+import { PlatformFilesystem, PlatformSandbox } from '@mastra/platform-workspace'
+
+export const workspace = new Workspace({
+  filesystem: new PlatformFilesystem(),
+  sandbox: new PlatformSandbox(),
+})
+```
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { workspace } from './workspace'
+
+export const mastra = new Mastra({
+  workspace,
+})
+```
+
+`PlatformFilesystem` and `PlatformSandbox` read their credentials from environment variables the platform injects at deploy time, so you don't pass any options on the platform.
+
+## Injected environment variables
+
+Every deploy that runs on a platform environment with a workspace receives these variables:
+
+| Variable                      | Contents                                                                                                                                                 |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MASTRA_PLATFORM_SECRET_KEY`  | Secret key scoped to the deploy. Used by the workspace providers to authenticate. `MASTRA_PLATFORM_ACCESS_TOKEN` is also injected as a deprecated alias. |
+| `MASTRA_PROJECT_ID`           | Project the deploy belongs to.                                                                                                                           |
+| `MASTRA_ENVIRONMENT_ID`       | Environment the deploy belongs to. Selects which sandbox pool the platform uses.                                                                         |
+| `MASTRA_PLATFORM_BUCKET_NAME` | Bucket name attached to the environment. Selects which bucket `PlatformFilesystem` reads and writes.                                                     |
+
+These names are reserved. If your project sets any of them explicitly, the platform-managed values take precedence.
+
+## Local development
+
+Reuse the same providers locally by putting the four variables in your `.env` file. Get the values from your project's Workspaces tab:
+
+```bash
+MASTRA_PLATFORM_SECRET_KEY=your-secret-key
+MASTRA_PROJECT_ID=your-project-id
+MASTRA_ENVIRONMENT_ID=your-environment-id
+MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name
+```
+
+`PlatformFilesystem` and `PlatformSandbox` behave the same locally as on the platform — they connect to the same bucket and sandbox pool for that environment. Use a `staging` or `preview` environment's variables for local runs if you want to keep production data isolated.
+
+For a purely offline loop that never touches the platform, swap the providers for [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) and [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) in a local build.
+
+## Inspect the workspace
+
+The Workspaces tab in your platform project shows, per environment:
+
+- Bucket status and its contents, with upload, download, and delete actions.
+- Recent sandbox sessions with their command, exit code, and duration.
+- Provisioning failures with a **Retry** action.
+
+## See also
+
+- [`PlatformFilesystem`](https://mastra.ai/reference/workspace/platform-filesystem) — reference for the filesystem provider.
+- [`PlatformSandbox`](https://mastra.ai/reference/workspace/platform-sandbox) — reference for the sandbox provider.
+- [Environments](https://mastra.ai/docs/mastra-platform/environments) — how environments scope workspaces, variables, and databases.

package/.docs/docs/mcp/overview.md

@@ -64,7 +64,7 @@ export const testMcpClient = new MCPClient({
 
 Visit [MCPClient](https://mastra.ai/reference/tools/mcp-client) for a full list of configuration options.
 
-> **Authentication:** For connecting to OAuth-protected MCP servers, see the [OAuth Authentication](https://mastra.ai/reference/tools/mcp-client) section.
+> **Authentication:** For connecting to OAuth-protected MCP servers — including completing the browser-based authorization flow with `authenticate()` — see the [OAuth Authentication](https://mastra.ai/reference/tools/mcp-client) section.
 
 ## Using `MCPClient` with an agent
 

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

@@ -8,7 +8,7 @@ Observational Memory (OM) is Mastra's memory system for long-context agentic mem
 
 ## Quickstart
 
-Enable `observationalMemory` in the memory options when creating your agent:
+Ensure you have `@mastra/memory` installed in your project. Set `observationalMemory: true` in your Memory config to enable Observational Memory.
 
 ```typescript
 import { Memory } from '@mastra/memory'
@@ -27,7 +27,54 @@ export const agent = new Agent({
 })
 ```
 
-That's it. The agent now has humanlike long-term memory that persists across conversations. Setting `observationalMemory: true` uses `google/gemini-2.5-flash` by default. Config objects also use this model unless you set a different one. To use a different model, pass it in the config object:
+**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:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { LibSQLStore } from '@mastra/libsql'
+import { Memory } from '@mastra/memory'
+
+const memory = new Memory({
+  storage: new LibSQLStore({
+    id: 'memory-storage',
+    url: 'file:./memory.db',
+  }),
+  options: {
+    observationalMemory: {
+      model: 'openai/gpt-5-mini',
+    },
+  },
+})
+
+const agent = new Agent({
+  id: 'memory-agent',
+  name: 'Memory Agent',
+  instructions: 'You are a helpful assistant.',
+  model: 'openai/gpt-5-mini',
+  memory,
+})
+
+const memoryOptions = {
+  resource: 'user-123',
+  thread: 'conversation-123',
+}
+
+const firstResponse = await agent.generate('Remember that my favorite color is blue.', {
+  memory: memoryOptions,
+})
+console.log(firstResponse.text)
+
+const secondResponse = await agent.generate('What is my favorite color?', {
+  memory: memoryOptions,
+})
+console.log(secondResponse.text)
+```
+
+The `resource` identifies the user or entity, while the `thread` identifies the conversation. Reuse both values to continue the same conversation. Observational Memory processes the stored history as it grows and replaces older messages with observations when its activation conditions are met.
+
+The agent now has humanlike long-term memory that persists across conversations. Setting `observationalMemory: true` uses `google/gemini-2.5-flash` by default. To use a different model, pass it in the config object:
 
 ```typescript
 const memory = new Memory({
@@ -237,6 +284,34 @@ new Extractor({
 })
 ```
 
+#### Read extracted values from a stream
+
+Extractor results are emitted when OM completes an observation or reflection. Read both completion data parts from the stream:
+
+```typescript
+const stream = await agent.stream('Remember that I prefer dark mode.')
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'data-om-observation-end' || chunk.type === 'data-om-buffering-end') {
+    const { operationType, extractedValues = {}, extractionFailures = [] } = chunk.data
+
+    for (const [slug, value] of Object.entries(extractedValues)) {
+      console.log(`${operationType} extractor ${slug}:`, value)
+    }
+
+    for (const failure of extractionFailures) {
+      console.error(`Extractor ${failure.slug} failed:`, failure.error)
+    }
+  }
+}
+```
+
+`extractedValues` uses each extractor's slug as its key. Both result fields are optional, and a failed extractor doesn't remove values from successful extractors.
+
+`data-om-observation-end` reports a synchronous completion. `data-om-buffering-end` reports completed background work. Its extractor metadata is persisted immediately, but the buffered content remains inactive until activation. Check `operationType` to determine whether the completed work was an observation or reflection.
+
+See the [`data-om-observation-end`](https://mastra.ai/reference/memory/observational-memory) and [`data-om-buffering-end`](https://mastra.ai/reference/memory/observational-memory) reference tables for the complete payloads.
+
 ### Working memory updates
 
 Use `observationalMemory.observation.manageWorkingMemory` to let the Observer manage working memory automatically. The main agent no longer needs to call the working memory tool while it handles the user request, so working memory updates don't depend on the agent remembering to make them.

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

@@ -81,6 +81,8 @@ Use memory when your agent needs to maintain multi-turn conversations that refer
 
 3. Add the storage provider to your main Mastra instance to enable memory across all configured agents.
 
+   **For AI agents:** Important: Add `id` to `LibSQLStore`.
+
    ```typescript
    import { Mastra } from '@mastra/core'
    import { LibSQLStore } from '@mastra/libsql'
@@ -151,6 +153,8 @@ To list all threads for a resource, or retrieve a specific thread, [use the memo
 
 For long-running conversations, raw message history grows until it fills the context window, degrading agent performance. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) solves this by running background agents that compress old messages into dense observations, keeping the context window small while preserving long-term memory.
 
+**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.
+
 ```typescript
 import { Agent } from '@mastra/core/agent'
 import { Memory } from '@mastra/memory'

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

@@ -127,6 +127,10 @@ 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.
 
+## 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.
+
 ## Related
 
 - [Observability overview](https://mastra.ai/docs/observability/overview)

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

@@ -126,9 +126,7 @@ export const mastra = new Mastra({
       },
     },
   }),
-  agents: {
-    /* your agents */
-  },
+  agents: {/* your agents */},
 })
 ```
 

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

@@ -425,9 +425,7 @@ To disable a signal, set the `signals` option:
 
 ```typescript
 new OtelExporter({
-  provider: {
-    /* ... */
-  },
+  provider: {/* ... */},
   signals: {
     traces: true, // default
     logs: false, // disable log export