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

package/.docs/reference/server/elysia-adapter.md

@@ -0,0 +1,184 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Elysia adapter
+
+The `@mastra/elysia` package provides a server adapter for running Mastra with [Elysia](https://elysiajs.com).
+
+> **Note:** For general adapter concepts, constructor options, and initialization flow, see [Server Adapters](https://mastra.ai/docs/server/server-adapters).
+
+## Installation
+
+Install the Elysia adapter and Elysia framework:
+
+**npm**:
+
+```bash
+npm install @mastra/elysia@latest elysia
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/elysia@latest elysia
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/elysia@latest elysia
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/elysia@latest elysia
+```
+
+## Usage example
+
+```typescript
+import { Elysia } from 'elysia'
+import { MastraServer } from '@mastra/elysia'
+import { mastra } from './mastra'
+
+const app = new Elysia()
+const server = new MastraServer({ app, mastra })
+
+await server.init()
+
+app.listen(3000)
+
+console.log('Server running on http://localhost:3000')
+```
+
+## Constructor parameters
+
+**app** (`Elysia`): Elysia app instance
+
+**mastra** (`Mastra`): Mastra instance
+
+**prefix** (`string`): Route path prefix (e.g., /api/v2) (Default: `''`)
+
+**openapiPath** (`string`): Path to serve OpenAPI spec (e.g., /openapi.json) (Default: `''`)
+
+**bodyLimitOptions** (`BodyLimitOptions`): Request body size limits
+
+**streamOptions** (`StreamOptions`): Stream redaction config. When true (default), redacts sensitive data from stream chunks before sending to clients. (Default: `{ redact: true }`)
+
+**customRouteAuthConfig** (`Map<string, boolean>`): Per-route auth overrides. Keys are METHOD:PATH (e.g., GET:/api/health). Value false makes route public, true requires auth.
+
+**tools** (`ToolsInput`): Available tools for the server
+
+**taskStore** (`InMemoryTaskStore`): Task store for A2A (Agent-to-Agent) operations
+
+**mcpOptions** (`MCPOptions`): MCP transport options. Set serverless: true for stateless environments like Vercel Edge.
+
+## Adding custom routes
+
+Add routes directly to the Elysia app:
+
+```typescript
+import { Elysia } from 'elysia'
+import { MastraServer } from '@mastra/elysia'
+import { mastra } from './mastra'
+
+const app = new Elysia()
+const server = new MastraServer({ app, mastra })
+
+// Before init - runs before Mastra middleware
+app.get('/early-health', () => ({ status: 'ok' }))
+
+await server.init()
+
+// After init - has access to Mastra context
+app.get('/custom', ({ mastra }) => {
+  return { agents: Object.keys(mastra.listAgents()) }
+})
+```
+
+> **Tip:** Routes added before `init()` run without Mastra context. Add routes after `init()` to access the Mastra instance and request context.
+
+When you want Mastra-managed auth and route metadata such as `requiresAuth`, prefer [`registerApiRoute()`](https://mastra.ai/reference/server/register-api-route). For raw Elysia routes mounted directly on `app`, use `createAuthMiddleware()`:
+
+```typescript
+import { Elysia } from 'elysia'
+import { createAuthMiddleware, MastraServer } from '@mastra/elysia'
+import { mastra } from './mastra'
+
+const app = new Elysia()
+const server = new MastraServer({ app, mastra })
+
+await server.init()
+
+app.get('/custom/protected', async ctx => {
+  const authResponse = await createAuthMiddleware({ mastra })(ctx)
+  if (authResponse) return authResponse
+
+  const user = ctx.requestContext.get('user')
+  return { user }
+})
+
+app.get('/custom/public', async ctx => {
+  const authResponse = await createAuthMiddleware({ mastra, requiresAuth: false })(ctx)
+  if (authResponse) return authResponse
+
+  return { ok: true }
+})
+```
+
+## Accessing context
+
+In Elysia handlers registered after `init()`, access Mastra context from the handler context:
+
+```typescript
+app.get('/custom', ({ mastra, requestContext, abortSignal }) => {
+  const agent = mastra.getAgent('myAgent')
+  const user = requestContext.get('user')
+
+  return { agent: agent.name, user, aborted: abortSignal.aborted }
+})
+```
+
+Available context keys:
+
+| Key                     | Description                                                    |
+| ----------------------- | -------------------------------------------------------------- |
+| `mastra`                | Mastra instance                                                |
+| `requestContext`        | Request context map                                            |
+| `abortSignal`           | Request cancellation signal                                    |
+| `registeredTools`       | Available tools                                                |
+| `taskStore`             | Task store for A2A operations                                  |
+| `customRouteAuthConfig` | Per-route auth overrides                                       |
+| `user`                  | Authenticated user in `requestContext` when auth is configured |
+
+## OpenAPI helpers
+
+Use `getMastraOpenAPIDoc()` when you need to pass Mastra's generated OpenAPI document to Elysia tooling such as `@elysiajs/openapi`:
+
+```typescript
+import { openapi } from '@elysiajs/openapi'
+import { Elysia } from 'elysia'
+import { getMastraOpenAPIDoc, MastraServer } from '@mastra/elysia'
+import { mastra } from './mastra'
+
+const app = new Elysia()
+const server = new MastraServer({ app, mastra })
+
+await server.init()
+
+app.use(
+  openapi({
+    documentation: getMastraOpenAPIDoc(server),
+  }),
+)
+```
+
+Call `clearMastraOpenAPICache(server)` if you need to regenerate the cached document for the same server instance.
+
+## MCP support
+
+The Elysia adapter supports both MCP HTTP and MCP SSE transports.
+
+## Manual initialization
+
+For custom middleware ordering, call each method separately instead of `init()`. See [manual initialization](https://mastra.ai/docs/server/server-adapters) for details.

package/.docs/reference/server/express-adapter.md

@@ -162,13 +162,13 @@ Available properties on `res.locals`:
 
 ## Adding middleware
 
-Add Express middleware before or after `init()`:
+Add Express middleware before `init()` to run it on every request. Mastra context isn't available at that point:
 
 ```typescript
 const app = express()
 app.use(express.json())
 
-// Middleware before init
+// Runs on every request, before Mastra context exists
 app.use((req, res, next) => {
   console.log(`${req.method} ${req.url}`)
   next()
@@ -176,14 +176,12 @@ app.use((req, res, next) => {
 
 const server = new MastraServer({ app, mastra })
 await server.init()
-
-// Middleware after init has access to Mastra context
-app.use((req, res, next) => {
-  const mastra = res.locals.mastra
-  next()
-})
 ```
 
+Middleware added after `init()` never runs for Mastra's routes. Express dispatches handlers in registration order, so middleware registered after the routes only applies to routes added later.
+
+This adapter can't run [`server.middleware`](https://mastra.ai/docs/server/middleware) handlers because they use Hono's signature, and it logs a warning when that option is set. If you need Express middleware between Mastra's context step and its routes, use the manual initialization flow below.
+
 ## Manual initialization
 
 For custom middleware ordering, call each method separately instead of `init()`. See [manual initialization](https://mastra.ai/docs/server/server-adapters) for details.

package/.docs/reference/server/hono-adapter.md

@@ -145,7 +145,7 @@ Available context keys:
 
 ## Adding middleware
 
-Add Hono middleware before or after `init()`:
+Add Hono middleware with `app.use()` before `init()` to run it on every request. Mastra context isn't available at that point:
 
 ```typescript
 import { Hono } from 'hono'
@@ -153,7 +153,7 @@ import { HonoBindings, HonoVariables, MastraServer } from '@mastra/hono'
 
 const app = new Hono<{ Bindings: HonoBindings; Variables: HonoVariables }>()
 
-// Middleware before init
+// Runs on every request, before Mastra context exists
 app.use('*', async (c, next) => {
   console.log(`${c.req.method} ${c.req.url}`)
   await next()
@@ -161,11 +161,24 @@ app.use('*', async (c, next) => {
 
 const server = new MastraServer({ app, mastra })
 await server.init()
+```
 
-// Middleware after init has access to Mastra context
-app.use('*', async (c, next) => {
-  const mastra = c.get('mastra')
-  await next()
+Middleware added after `init()` never runs for Mastra's routes. Hono dispatches handlers in registration order, so middleware registered after the routes only applies to routes added later.
+
+To run middleware with Mastra context on Mastra's routes, use [`server.middleware`](https://mastra.ai/docs/server/middleware) in the Mastra config. The adapter registers it during `init()`, after the context step and before any route. These handlers are skipped for routes declared public with `requiresAuth: false`, so they can't block endpoints such as the Studio sign-in routes:
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+export const mastra = new Mastra({
+  server: {
+    middleware: [
+      async (c, next) => {
+        c.get('requestContext').set('locale', c.req.header('accept-language') ?? 'en')
+        await next()
+      },
+    ],
+  },
 })
 ```
 

package/.docs/reference/storage/turso.md

@@ -0,0 +1,88 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Turso Storage
+
+Use `@mastra/turso` to store Mastra agents, workflows, memory, and other storage domains in a local [Turso Database](https://github.com/tursodatabase/turso) file.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/turso
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/turso
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/turso
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/turso
+```
+
+## Usage
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { TursoStore } from '@mastra/turso'
+
+export const mastra = new Mastra({
+  storage: new TursoStore({
+    id: 'local-storage',
+    path: './mastra.db',
+  }),
+})
+```
+
+## Constructor options
+
+- `id` (required): Unique identifier for the storage instance.
+- `path` (required unless `client` is provided): Path to the local database file.
+- `client`: A compatible SQLite client to use instead of creating a native Turso client.
+- `readonly`: Opens the database in read-only mode.
+- `fileMustExist`: Requires the database file to exist before opening it.
+- `timeout`: Connection timeout in milliseconds.
+- `defaultQueryTimeout`: Default query timeout in milliseconds.
+- `tracing`: Native driver tracing level: `info`, `debug`, or `trace`.
+- `experimental`: Native Turso Database experimental features to enable.
+- `maxRetries`: Maximum number of retries for retryable writes.
+- `initialBackoffMs`: Initial retry delay in milliseconds.
+- `disableInit`: Disables automatic storage initialization.
+- `retention`: Retention policies for supported storage domains.
+
+## Platform support
+
+The native driver supports macOS on arm64, Windows on x64, and glibc-based Linux on x64 and arm64. Use `getTursoDatabaseSupport()` when your application needs to choose a fallback on unsupported systems.
+
+```typescript
+import { getTursoDatabaseSupport } from '@mastra/turso'
+
+const support = getTursoDatabaseSupport()
+if (!support.supported) {
+  console.warn(support.reason)
+}
+```
+
+## Experimental features
+
+Experimental Turso Database features are disabled by default. Enable only the features your application requires.
+
+```typescript
+const storage = new TursoStore({
+  id: 'multiprocess-storage',
+  path: './mastra.db',
+  experimental: ['multiprocess_wal'],
+})
+```
+
+`@mastra/turso` provides local-file Mastra storage. It doesn't connect to remote libSQL databases and doesn't include a vector store.

package/.docs/reference/streaming/ChunkType.md

@@ -272,8 +272,36 @@ Contains file data.
 
 **payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider-specific metadata
 
+### reasoning-file
+
+Contains a file generated by the model as part of its reasoning. Emitted by providers on the AI SDK v7 specification.
+
+**type** (`"reasoning-file"`): Chunk type identifier
+
+**payload** (`ReasoningFilePayload`): Reasoning file data
+
+**payload.data** (`string | Uint8Array`): The file data
+
+**payload.base64** (`string`): Base64 encoded data if applicable
+
+**payload.mimeType** (`string`): MIME type of the file
+
+**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider-specific metadata
+
 ## Control chunks
 
+### custom
+
+Contains a provider-specific content block that doesn't map to any other standardized chunk type. Emitted by providers on the AI SDK v7 specification.
+
+**type** (`"custom"`): Chunk type identifier
+
+**payload** (`CustomPayload`): Custom provider content
+
+**payload.kind** (`string`): The kind of custom content, in the format {provider}.{provider-type}
+
+**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider-specific metadata
+
 ### start
 
 Signals the start of streaming.
@@ -324,7 +352,7 @@ Signals the completion of a processing step.
 
 ### raw
 
-Contains raw data from the provider.
+Contains raw data from the provider. Content types Mastra doesn't recognize are also emitted as `raw` chunks rather than being discarded. Raw chunks only appear when `includeRawChunks` is enabled.
 
 **type** (`"raw"`): Chunk type identifier
 

package/.docs/reference/streaming/agents/stream.md

@@ -82,7 +82,7 @@ const stream = await agent.stream('message for agent')
 
 **options.onAbort** (`(event: { steps: any[]; text?: string }) => Promise<void> | void`): Callback function called when the stream is aborted. steps contains the steps that completed before the abort, and text contains the assistant text streamed so far for the step that was in flight.
 
-**options.abortSignal** (`AbortSignal`): Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated, including any in-flight subagent runs the agent delegated to.
+**options.abortSignal** (`AbortSignal`): Signal object that allows you to abort the agent's execution, including in-flight subagent runs. Canceled runs continue through output processors. When writable memory is configured, built-in memory processors persist submitted messages, completed tool results, and assistant output available when terminal processing runs. Output that doesn't reach terminal processing isn't persisted. Custom output processors can transform or interrupt this behavior before memory processors run.
 
 **options.activeTools** (`Array<keyof ToolSet> | undefined`): Array of active tool names that can be used during execution.
 
@@ -180,8 +180,6 @@ const stream = await agent.stream('message for agent')
 
 **options.savePerStep** (`boolean`): Save messages incrementally after each stream step completes (default: false).
 
-**options.persistPartialOnAbort** (`boolean`): Save the assistant text that was streamed before an abort to memory (default: false). Only text emitted before the abort is persisted; output a provider keeps producing after cancellation is discarded, and nothing is saved when no text was streamed.
-
 **options.requireToolApproval** (`boolean`): When true, all tool calls require explicit approval before execution. The stream will emit tool-call-approval chunks and pause until approveToolCall() or declineToolCall() is called.
 
 **options.autoResumeSuspendedTools** (`boolean`): When true, automatically resumes suspended tools when the user sends a new message on the same thread. The agent extracts resumeData from the user's message based on the tool's resumeSchema. Requires memory to be configured.

package/.docs/reference/tools/mcp-client.md

@@ -232,15 +232,17 @@ Retrieves all tools from all configured servers, with tool names namespaced by t
 Set `perServerTimeoutMs` to limit how long discovery waits for each server. Servers that finish within the limit remain in `tools`. Timed-out servers appear in `errors`, and `durations` reports each server's discovery time in milliseconds.
 
 ```typescript
-const { tools, errors, durations } = await mcp.listToolsWithErrors({
+const { tools, errors, errorDetails, durations } = await mcp.listToolsWithErrors({
   perServerTimeoutMs: 3_000,
 })
 
 new Agent({ id: 'agent', tools })
-console.log(errors, durations)
+console.log(errors, errorDetails, durations)
 ```
 
-When called without options, the method returns only `tools` and `errors`.
+`errors` remains a string map for backward compatibility. `errorDetails` provides the same message plus machine-readable `httpStatus` and transport `code` fields when the underlying error exposes them. When an HTTP status is available, the legacy message also includes an `(HTTP nnn)` suffix.
+
+When called without options, the method omits only `durations`; `tools`, `errors`, and `errorDetails` are always returned.
 
 ### `listToolsets()`
 
@@ -257,15 +259,15 @@ const res = await agent.stream(prompt, {
 Returns toolsets grouped by server name, along with per-server discovery errors. Set `perServerTimeoutMs` to limit each server independently and include per-server `durations` in milliseconds.
 
 ```typescript
-const { toolsets, errors, durations } = await mcp.listToolsetsWithErrors({
+const { toolsets, errors, errorDetails, durations } = await mcp.listToolsetsWithErrors({
   perServerTimeoutMs: 3_000,
 })
 
 const res = await agent.stream(prompt, { toolsets })
-console.log(errors, durations)
+console.log(errors, errorDetails, durations)
 ```
 
-When called without options, the method returns only `toolsets` and `errors`.
+When called without options, the method omits only `durations`; `toolsets`, `errors`, and `errorDetails` are always returned.
 
 ### `listToolDefinitions()`
 
@@ -286,7 +288,7 @@ Like `listToolDefinitions()`, but also returns per-server errors for servers tha
 Set `perServerTimeoutMs` to limit each server independently. When options are provided, `durations` reports each server's discovery time in milliseconds.
 
 ```typescript
-const { definitions, errors, durations } = await mcp.listToolDefinitionsWithErrors({
+const { definitions, errors, errorDetails, durations } = await mcp.listToolDefinitionsWithErrors({
   perServerTimeoutMs: 3_000,
 })
 
@@ -294,10 +296,10 @@ if (Object.keys(errors).length === 0) {
   await cache.set('mcp-tools', JSON.stringify(definitions))
 }
 
-console.log(durations)
+console.log(errorDetails, durations)
 ```
 
-When called without options, the method returns only `definitions` and `errors`.
+When called without options, the method omits only `durations`; `definitions`, `errors`, and `errorDetails` are always returned.
 
 ### `toolFromDefinition()`
 
@@ -441,6 +443,18 @@ for (const serverName in resourcesByServer) {
 }
 ```
 
+#### `resources.listWithErrors(options?)`
+
+Preserves successful resources while reporting failed servers through legacy string `errors` and structured `errorDetails`. Pass `perServerTimeoutMs` to bound each server independently and include `durations`.
+
+```typescript
+const { resources, errors, errorDetails, durations } = await mcpClient.resources.listWithErrors({
+  perServerTimeoutMs: 3_000,
+})
+
+console.log(resources, errors, errorDetails, durations)
+```
+
 #### `resources.templates()`
 
 Retrieves all available resource templates from all connected MCP servers, grouped by server name.
@@ -458,6 +472,15 @@ for (const serverName in templatesByServer) {
 }
 ```
 
+#### `resources.templatesWithErrors(options?)`
+
+Returns successful resource templates together with per-server string `errors`, structured `errorDetails`, and optional `durations`.
+
+```typescript
+const { templates, errors, errorDetails } = await mcpClient.resources.templatesWithErrors()
+console.log(templates, errors, errorDetails)
+```
+
 #### `resources.read(serverName: string, uri: string)`
 
 Reads the content of a specific resource from a server.
@@ -711,6 +734,15 @@ for (const serverName in promptsByServer) {
 }
 ```
 
+#### `prompts.listWithErrors(options?)`
+
+Returns successful prompts together with per-server string `errors`, structured `errorDetails`, and optional `durations`.
+
+```typescript
+const { prompts, errors, errorDetails } = await mcpClient.prompts.listWithErrors()
+console.log(prompts, errors, errorDetails)
+```
+
 #### `prompts.get({ serverName, name, args?, version? })`
 
 Retrieves a specific prompt and its messages from a server.

package/.docs/reference/vectors/mongodb.md

@@ -2,7 +2,7 @@
 
 # MongoDB vector store
 
-The `MongoDBVector` class provides vector search using [MongoDB Atlas Vector Search](https://www.mongodb.com/docs/atlas/atlas-vector-search/). It enables efficient similarity search and metadata filtering within your MongoDB collections.
+The `MongoDBVector` class provides vector search using [MongoDB Vector Search](https://www.mongodb.com/docs/atlas/atlas-vector-search/). It enables efficient similarity search and metadata filtering within your MongoDB collections.
 
 ## Installation
 
@@ -89,11 +89,11 @@ Creates a new vector index (collection) in MongoDB.
 
 **metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
 
-**filterFields** (`string[]`): Metadata field names to declare as filter fields in the Atlas vectorSearch index (registered as metadata.\<field>). Queries that filter only on declared fields are pushed directly into $vectorSearch instead of pre-filtering candidate \_ids, avoiding the 16 MB BSON limit on large result sets. Filters that reference an undeclared field, or use an operator $vectorSearch does not support, fall back to the pre-filter automatically.
+**filterFields** (`string[]`): Metadata field names to declare as filter fields in the MongoDB vectorSearch index (registered as metadata.\<field>). Queries that filter only on declared fields are pushed directly into $vectorSearch instead of pre-filtering candidate \_ids, avoiding the 16 MB BSON limit on large result sets. Filters that reference an undeclared field, or use an operator $vectorSearch does not support, fall back to the pre-filter automatically.
 
 **collectionName** (`string`): Store the vectors on an existing (operational) collection instead of a managed collection named after the index. The collection is never created or dropped by this store when set. Defaults to indexName.
 
-**searchIndexName** (`string`): Name for the Atlas vectorSearch index created on the collection. Defaults to ${indexName}\_vector\_index.
+**searchIndexName** (`string`): Name for the MongoDB vectorSearch index created on the collection. Defaults to ${indexName}\_vector\_index.
 
 **allowWrites** (`boolean`): Opt-in to write operations (upsert, updateVector, deleteVector, deleteVectors) on a bring-your-own collection. By default a BYO index is read-only: the store never modifies or deletes caller-owned operational documents. Ignored for managed collections, which are always writable. The policy is persisted with the index registration and survives restarts. (Default: `false`)
 
@@ -143,7 +143,7 @@ Searches for similar vectors with optional metadata filtering.
 
 ### `createSearchIndex()`
 
-Provisions an Atlas Search (BM25/full-text) index on the collection backing an index and records it as the text-search index that `textQuery()` and `hybridQuery()` will target.
+Provisions a MongoDB Search (BM25/full-text) index on the collection backing an index and records it as the text-search index that `textQuery()` and `hybridQuery()` will target.
 
 **Managed vs. bring-your-own collections:**
 
@@ -159,7 +159,7 @@ Naming:
 
 **fields** (`string[]`): Field names to index for full-text search. Omit for dynamic mapping (all string fields).
 
-**searchIndexName** (`string`): Name for the Atlas Search index. When fields is provided and this is omitted, a distinct default name that is unique per logical index is used, so the field mapping is not shadowed by the auto-created dynamic index and two logical indexes on the same collection do not collide. (Default: ``${collectionName}_search_index (or ${collectionName}_${indexName}_search_fields_index when `fields` is given)``)
+**searchIndexName** (`string`): Name for the MongoDB Search index. When fields is provided and this is omitted, a distinct default name that is unique per logical index is used, so the field mapping is not shadowed by the auto-created dynamic index and two logical indexes on the same collection do not collide. (Default: ``${collectionName}_search_index (or ${collectionName}_${indexName}_search_fields_index when `fields` is given)``)
 
 **waitUntilReady** (`boolean`): When true, block until the provisioned full-text index reports READY before resolving. Defaults to false to avoid surprising latency; call waitForSearchIndexReady() explicitly if you prefer to await separately. (Default: `false`)
 
@@ -174,7 +174,7 @@ The field-mapped index name includes the logical `indexName`, so two logical ind
 
 ### `waitForSearchIndexReady()`
 
-Waits for the full-text (BM25) search index of an index to become READY. `waitForIndexReady()` polls only the vectorSearch index; `createSearchIndex()` returns while the Atlas Search full-text index is still building, so an immediate `textQuery()`/`hybridQuery()` can intermittently fail. Call this (or pass `waitUntilReady: true` to `createSearchIndex()`) to block until the resolved text index reports READY.
+Waits for the full-text (BM25) search index of an index to become READY. `waitForIndexReady()` polls only the vectorSearch index; `createSearchIndex()` returns while the MongoDB Search full-text index is still building, so an immediate `textQuery()`/`hybridQuery()` can intermittently fail. Call this (or pass `waitUntilReady: true` to `createSearchIndex()`) to block until the resolved text index reports READY.
 
 **indexName** (`string`): Logical name of the index whose text index to wait for
 
@@ -191,7 +191,7 @@ await store.waitForSearchIndexReady({ indexName: 'precedents' })
 
 ### `textQuery()`
 
-Runs a full-text (BM25) search against an Atlas Search index. By default it targets the text-search index recorded for this index (set by `createSearchIndex()`, or the dynamic `${collectionName}_search_index` auto-created by `createIndex()`). Pass `searchIndexName` to target a specific index for this call.
+Runs a full-text (BM25) search against a MongoDB Search index. By default it targets the text-search index recorded for this index (set by `createSearchIndex()`, or the dynamic `${collectionName}_search_index` auto-created by `createIndex()`). Pass `searchIndexName` to target a specific index for this call.
 
 Metadata filters here (like `hybridQuery()`) are applied via a `$match` stage. For the vector branch of `hybridQuery()`, filters on fields not declared via `filterFields` at index creation are transparently materialised as candidate `_id`s (the same fallback `query()` uses), so undeclared-field filters don't error.
 
@@ -220,7 +220,7 @@ const results = await store.textQuery({
 
 ### `hybridQuery()`
 
-Runs a hybrid search that fuses vector similarity and full-text results using MongoDB's server-side `$rankFusion`. It requires MongoDB >= 8.0 and is generally available from 8.1. On 8.0.x, it may require a MongoDB support case for enablement. It runs where enabled, including Atlas 8.0.x. A full-text search index must exist: it's auto-created for managed indexes, but for a bring-your-own collection you must call `createSearchIndex()` first (opt-in).
+Runs a hybrid search that fuses vector similarity and full-text results using MongoDB's server-side `$rankFusion`. It requires MongoDB >= 8.0 and is generally available from 8.1. On 8.0.x, it may require a MongoDB support case for enablement. It runs where enabled, including MongoDB Atlas 8.0.x. A full-text search index must exist: it's auto-created for managed indexes, but for a bring-your-own collection you must call `createSearchIndex()` first (opt-in).
 
 **indexName** (`string`): Name of the Mastra index to search
 
@@ -253,7 +253,7 @@ const results = await store.hybridQuery({
 })
 ```
 
-`hybridQuery()` requires MongoDB >= 8.0 for the `$rankFusion` stage. The stage is generally available from 8.1. On 8.0.x, it may need a MongoDB support case to enable and runs where enabled, such as Atlas 8.0.x. If you're running an older version, or `$rankFusion` isn't enabled on your 8.0.x deployment, use `query()` and `textQuery()` separately and merge the results client-side.
+`hybridQuery()` requires MongoDB >= 8.0 for the `$rankFusion` stage. The stage is generally available from 8.1. On 8.0.x, it may need a MongoDB support case to enable and runs where enabled, such as MongoDB Atlas 8.0.x. If you're running an older version, or `$rankFusion` isn't enabled on your 8.0.x deployment, use `query()` and `textQuery()` separately and merge the results client-side.
 
 ### `describeIndex()`
 
@@ -276,7 +276,7 @@ interface IndexStats {
 Deletes a vector index. Behavior depends on how the index was created:
 
 - **Managed index** (created without `collectionName`): drops the entire collection and all its data.
-- **Bring-your-own index** (created with `collectionName`): drops the Atlas vectorSearch index. If `createSearchIndex()` provisioned a companion full-text search index, it drops that index too. The caller's operational collection and its documents are preserved. This store never drops a collection it didn't create.
+- **Bring-your-own index** (created with `collectionName`): drops the MongoDB vectorSearch index. If `createSearchIndex()` provisioned a companion full-text search index, it drops that index too. The caller's operational collection and its documents are preserved. This store never drops a collection it didn't create.
 
 The BYO classification is recorded durably when the index is created, so it's applied correctly even by a different process (e.g. an index created by a setup job and later deleted by a long-lived service). Always pass the **logical index name** (the `indexName` used at `createIndex`), not the physical collection name.
 
@@ -429,7 +429,7 @@ await store.createSearchIndex({ indexName: 'precedents', fields: ['note'] })
 
 Embeddings are numeric vectors used by memory's `semanticRecall` to retrieve related messages by meaning (not keywords).
 
-> **Note:** MongoDB Atlas Vector Search is recommended for production use. For self-hosted deployments, Vector Search is available with [local Atlas deployments via the Atlas CLI](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-local/).
+> **Note:** MongoDB Vector Search is recommended for production use. For self-hosted deployments, Vector Search is available with [local Atlas deployments via the Atlas CLI](https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-local/).
 
 This setup uses FastEmbed, a local embedding model, to generate vector embeddings. To use this, install `@mastra/fastembed`:
 

package/.docs/reference/vectors/pg.md

@@ -173,6 +173,8 @@ interface PGIndexStats {
 }
 ```
 
+`count` is an exact `SELECT COUNT(*)`, which scans the whole table, so avoid calling `describeIndex()` on a hot path for a large index. Reads and writes never pay for it: they only use the index metadata, which comes from the Postgres catalog.
+
 ### `deleteIndex()`
 
 **indexName** (`string`): Name of the index to delete

package/.docs/reference/workspace/local-sandbox.md

@@ -54,6 +54,8 @@ const response = await agent.generate('Run npm install')
 
 **nativeSandbox** (`NativeSandboxConfig`): Configuration for native sandboxing (see NativeSandboxConfig below).
 
+`start()` reports `{ outcome: 'created' }` when the working directory didn't exist yet and `{ outcome: 'connected' }` when it reattaches to an existing directory. See [`start()`](https://mastra.ai/reference/workspace/sandbox) for the shared contract.
+
 ## `NativeSandboxConfig`
 
 Configuration options for native OS sandboxing (used with `isolation: 'seatbelt'` or `'bwrap'`).

package/.docs/reference/workspace/platform-sandbox.md

@@ -118,6 +118,8 @@ const result = await sandbox.executeCommand('cat', ['/workspace/state.json'])
 
 When `sandboxId` is set, `environmentId` isn't required because the sandbox already exists.
 
+`start()` reports `{ outcome: 'connected' }` on reattach and `{ outcome: 'created' }` on a fresh provision (including a checkpoint-recovered boot, which is a new VM even when its filesystem was restored). See [`start()`](https://mastra.ai/reference/workspace/sandbox) for the shared contract.
+
 ### Checkpoint recovery
 
 The constructor `id` (explicit or auto-generated) is sent to the platform on `POST /sandbox` as an advisory recovery key:
@@ -226,7 +228,7 @@ console.log(result.exitCode)
 
 ## Methods
 
-**start** (`() => Promise<void>`): Provision the remote sandbox, or reattach when sandboxId was passed to the constructor. Idempotent once the sandbox is running. A destroyed reattach target falls through to a fresh provision.
+**start** (`() => Promise<SandboxStartResult>`): Provision the remote sandbox, or reattach when sandboxId was passed to the constructor. Idempotent once the sandbox is running. A destroyed reattach target falls through to a fresh provision.
 
 **destroy** (`() => Promise<void>`): Tear down the remote sandbox and clear the cached exec lease. A subsequent start() provisions a fresh sandbox (or restores from checkpoint when a stable id is set).