@mastra/mcp-docs-server 1.2.23-alpha.1 → 1.2.23-alpha.10

package/.docs/reference/rag/vector-databases.md

@@ -35,11 +35,11 @@ MongoDB Vector Search is a good solution for teams who want to consolidate vecto
 
 ### Using VoyageAI with MongoDB
 
-MongoDB works seamlessly with VoyageAI's embedding models, which are optimized for retrieval tasks. For complete examples and specialized models, see the [VoyageAI embeddings documentation](https://mastra.ai/models/embeddings) and [MongoDB vector reference](https://mastra.ai/reference/vectors/mongodb).
+MongoDB works directly with VoyageAI's embedding models, which are optimized for retrieval tasks. For complete examples and specialized models, see the [VoyageAI embeddings documentation](https://mastra.ai/models/embeddings) and [MongoDB vector reference](https://mastra.ai/reference/vectors/mongodb).
 
 ### Hybrid Search (Vector + Full-Text)
 
-MongoDB supports hybrid search that fuses vector similarity with BM25 full-text search using server-side `$rankFusion` (requires MongoDB >= 8.0; generally available from 8.1, and enabled on MongoDB Atlas 8.0.x). This is useful when you want to combine semantic and keyword-based retrieval:
+MongoDB supports hybrid search that combines vector similarity with BM25 full-text search through server-side `$rankFusion`. It requires MongoDB 8.0 or later, is generally available from 8.1, and is enabled on MongoDB Atlas 8.0.x. Use it to combine semantic retrieval with keyword-based results:
 
 ```ts
 await store.createSearchIndex({ indexName: 'myCollection', fields: ['text'] })
@@ -107,7 +107,7 @@ await store.upsert({
 
 ### Using Oracle Database Vector Search
 
-OracleDB stores embeddings in native `VECTOR` columns and metadata in Oracle JSON. Exact search is the default; HNSW and IVF indexes can be configured for tuned deployments.
+OracleDB stores embeddings in native `VECTOR` columns and metadata in Oracle JSON. Exact search is the default. HNSW and IVF indexes can be configured for tuned deployments.
 
 **Pinecone**:
 
@@ -239,8 +239,8 @@ const store = new UpstashVector({
   token: process.env.UPSTASH_TOKEN,
 })
 
-// There is no store.createIndex call here, Upstash creates indexes (known as namespaces in Upstash) automatically
-// when you upsert if that namespace does not exist yet.
+// Upstash creates indexes (known as namespaces) automatically, so no store.createIndex call is needed here
+// when you upsert if that namespace doesn't exist yet.
 await store.upsert({
   indexName: 'myCollection', // the namespace name in Upstash
   vectors: embeddings,
@@ -426,20 +426,20 @@ Collection and index names must:
 
 - Start with a letter or underscore
 - Be up to 120 bytes long
-- Contain only letters, numbers, underscores, or dots
-- Cannot contain `$` or the null character
+- Contain only letters, numbers, underscore characters, or dots
+- Can't contain `$` or the null character
 - Example: `my_collection.123` is valid
-- Example: `my-index` is not valid (contains hyphen)
-- Example: `My$Collection` is not valid (contains `$`)
+- Example: `my-index` isn't valid (contains hyphen)
+- Example: `My$Collection` isn't valid (contains `$`)
 
 **PgVector**:
 
 Index names must:
 
 - Start with a letter or underscore
-- Contain only letters, numbers, and underscores
+- Contain only letters, numbers, and underscore characters
 - Example: `my_index_123` is valid
-- Example: `my-index` is not valid (contains hyphen)
+- Example: `my-index` isn't valid (contains hyphen)
 
 **OracleDB**:
 
@@ -466,7 +466,7 @@ Index names must:
 - Have a combined length (with project ID) under 52 characters
 
   - Example: `my-index-123` is valid
-  - Example: `my.index` is not valid (contains dot)
+  - Example: `my.index` isn't valid (contains dot)
 
 **Qdrant**:
 
@@ -482,7 +482,7 @@ Collection names must:
 
 - Example: `my_collection_123` is valid
 
-- Example: `my/collection` is not valid (contains slash)
+- Example: `my/collection` isn't valid (contains slash)
 
 **Chroma**:
 
@@ -490,11 +490,11 @@ Collection names must:
 
 - Be 3-63 characters long
 - Start and end with a letter or number
-- Contain only letters, numbers, underscores, or hyphens
+- Contain only letters, numbers, underscore characters, or hyphens
 - Not contain consecutive periods (..)
 - Not be a valid IPv4 address
 - Example: `my-collection-123` is valid
-- Example: `my..collection` is not valid (consecutive periods)
+- Example: `my..collection` isn't valid (consecutive periods)
 
 **Astra**:
 
@@ -502,18 +502,18 @@ Collection names must:
 
 - Not be empty
 - Be 48 characters or less
-- Contain only letters, numbers, and underscores
+- Contain only letters, numbers, and `_` characters
 - Example: `my_collection_123` is valid
-- Example: `my-collection` is not valid (contains hyphen)
+- Example: `my-collection` isn't valid (contains hyphen)
 
 **libSQL**:
 
 Index names must:
 
 - Start with a letter or underscore
-- Contain only letters, numbers, and underscores
+- Contain only letters, numbers, and `_` characters
 - Example: `my_index_123` is valid
-- Example: `my-index` is not valid (contains hyphen)
+- Example: `my-index` isn't valid (contains hyphen)
 
 **Upstash**:
 
@@ -532,7 +532,7 @@ Namespace names must:
 
 - Example: `MyNamespace123` is valid
 
-- Example: `_namespace` is not valid (starts with underscore)
+- Example: `_namespace` isn't valid (starts with underscore)
 
 **Cloudflare**:
 
@@ -543,19 +543,19 @@ Index names must:
 - Contain only lowercase ASCII letters, numbers, and dashes
 - Use dashes instead of spaces
 - Example: `my-index-123` is valid
-- Example: `My_Index` is not valid (uppercase and underscore)
+- Example: `My_Index` isn't valid (uppercase and underscore)
 
 **OpenSearch**:
 
 Index names must:
 
 - Use only lowercase letters
-- Not begin with underscores or hyphens
+- Not begin with underscore characters or hyphens
 - Not contain spaces, commas
 - Not contain special characters (e.g. `:`, `"`, `*`, `+`, `/`, `\`, `|`, `?`, `#`, `>`, `<`)
 - Example: `my-index-123` is valid
-- Example: `My_Index` is not valid (contains uppercase letters)
-- Example: `_myindex` is not valid (begins with underscore)
+- Example: `My_Index` isn't valid (contains uppercase letters)
+- Example: `_myindex` isn't valid (begins with underscore)
 
 **Elasticsearch**:
 
@@ -563,29 +563,29 @@ Index names must:
 
 - Use only lowercase letters
 - Not exceed 255 bytes (counting multi-byte characters)
-- Not begin with underscores, hyphens, or plus signs
+- Not begin with underscore characters, hyphens, or plus signs
 - Not contain spaces, commas
 - Not contain special characters (e.g. `:`, `"`, `*`, `+`, `/`, `\`, `|`, `?`, `#`, `>`, `<`)
 - Not be "." or ".."
 - Not start with "." (deprecated except for system/hidden indices)
 - Example: `my-index-123` is valid
-- Example: `My_Index` is not valid (contains uppercase letters)
-- Example: `_myindex` is not valid (begins with underscore)
-- Example: `.myindex` is not valid (begins with dot, deprecated)
+- Example: `My_Index` isn't valid (contains uppercase letters)
+- Example: `_myindex` isn't valid (begins with underscore)
+- Example: `.myindex` isn't valid (begins with dot, deprecated)
 
 **S3 Vectors**:
 
 Index names must:
 
 - Be unique within the same vector bucket
-- Be 3–63 characters long
+- Be between 3 and 63 characters long
 - Use only lowercase letters (`a–z`), numbers (`0–9`), hyphens (`-`), and dots (`.`)
 - Begin and end with a letter or number
 - Example: `my-index.123` is valid
-- Example: `my_index` is not valid (contains underscore)
-- Example: `-myindex` is not valid (begins with hyphen)
-- Example: `myindex-` is not valid (ends with hyphen)
-- Example: `MyIndex` is not valid (contains uppercase letters)
+- Example: `my_index` isn't valid (contains underscore)
+- Example: `-myindex` isn't valid (begins with hyphen)
+- Example: `myindex-` isn't valid (ends with hyphen)
+- Example: `MyIndex` isn't valid (contains uppercase letters)
 
 ### Upserting Embeddings
 

package/.docs/reference/server/create-route.md

@@ -80,7 +80,7 @@ Returns a `ServerRoute` object that can be registered with an adapter or passed
 
 ### Register through `server.apiRoutes`
 
-Routes created with `createRoute()` can be passed to `server.apiRoutes`. The adapter registers them with runtime validation, typed handler parameters, and generated OpenAPI metadata. See [Custom API routes](https://mastra.ai/docs/server/custom-api-routes) for details.
+Routes created with `createRoute()` can be passed to `server.apiRoutes`, where the adapter adds runtime validation and typed handler parameters while generating OpenAPI metadata. See [Custom API routes](https://mastra.ai/docs/server/custom-api-routes) for details.
 
 ```typescript
 import { Mastra } from '@mastra/core'

package/.docs/reference/signals/task-signal-provider.md

@@ -44,7 +44,7 @@ Task tracking requires a memory-backed thread (`threadId` + `resourceId`). Witho
 
 ### Agent integration
 
-These methods are called automatically by the Agent when the provider is passed to `signals`. You normally don't call them directly.
+The Agent calls these methods automatically when the provider is passed to `signals`, so you normally don't call them directly.
 
 #### `getTools()`
 

package/.docs/reference/storage/composite.md

@@ -255,7 +255,7 @@ const thread = await memoryStore?.getThreadById({ threadId: '...' })
 
 ## Closing connections
 
-`close()` releases the connections of the stores a composite was built from: the `default` and `editor` stores, plus any domain that owns its own client. Each store is closed once, even when it backs several domains. When passed to the Mastra class, `close()` is called by `shutdown()`:
+`close()` releases connections for the stores used by a composite, including the `default` and `editor` stores and any domain with its own client. Each store closes once even if it backs several domains. When the composite is passed to the Mastra class, `shutdown()` calls `close()`:
 
 ```typescript
 import { MastraCompositeStore } from '@mastra/core/storage'

package/.docs/reference/storage/retention.md

@@ -4,7 +4,7 @@
 
 # Storage retention
 
-Storage grows without bound by default. Retention is an opt-in, age-based cleanup system: you declare per-table `maxAge` policies in the `retention` config, then call `storage.prune()` to delete rows older than their configured age. Anything you don't configure is kept forever, so there is no behavior change until you opt in.
+Because storage grows without bound by default, Mastra provides an opt-in, age-based retention system. Declare per-table `maxAge` policies in the `retention` config, then call `storage.prune()` to delete rows older than their configured age. Unconfigured data is kept forever, so behavior doesn't change until you opt in.
 
 `prune()` deletes rows. It caps growth and is safe to run against large tables (batched, bounded, resumable, cancellable). It never reclaims disk: on SQLite/libSQL the freed pages are reused by future writes so the file stops growing, but handing disk back to the OS (for example a `VACUUM`) is left to the underlying database and the operator to manage.
 
@@ -37,7 +37,7 @@ const storage = new LibSQLStore({
 const results = await storage.prune()
 ```
 
-`retention` is fully typed. Keys must be real domain keys, and each table key must be one the domain declares as retention-eligible. Passing the object straight into a store config type-checks it; if you build it standalone, use `satisfies RetentionConfig` so unknown domains or tables are compile errors:
+`retention` is fully typed. Domain keys must exist, and their table keys must be declared retention-eligible. Store configs type-check objects passed directly. When building an object separately, use `satisfies RetentionConfig` so unknown domains or tables produce compile errors:
 
 ```typescript
 import type { RetentionConfig } from '@mastra/core/storage'
@@ -67,7 +67,7 @@ Set the `retention` field on the store config.
 
 ### Retention-eligible tables
 
-Each domain declares which of its tables can be age-pruned and which timestamp column anchors the comparison. The anchor is chosen so `maxAge` means what you'd expect for that data. Append-only logs use creation time, and live state uses last activity. Jobs and runs use completion time, so in-flight work is never pruned.
+Each domain specifies its age-prunable tables and the timestamp column that anchors comparison, chosen so `maxAge` matches the meaning of the data. Append-only logs use creation time, live state uses last activity, and jobs or runs use completion time so in-flight work isn't pruned.
 
 | Domain            | Table key          | Anchor column    | `maxAge` measures                                                |
 | ----------------- | ------------------ | ---------------- | ---------------------------------------------------------------- |
@@ -158,7 +158,7 @@ interface PruneResult {
 
 ## Running prune on a schedule
 
-`prune()` has no built-in scheduler: you decide when it runs. Because it's bounded, a single call may not delete everything. When any result has `done: false`, eligible rows remain and you call again on the next tick. This keeps each invocation short and lets a large backlog drain over several runs.
+`prune()` has no built-in scheduler, so you decide when it runs. A bounded call may leave eligible rows, indicated by any result with `done: false`. Call it again on the next tick. Short invocations let a large backlog drain over several runs.
 
 ```typescript
 // Runs on your own cron (node-cron, a workflow schedule, an external job, etc.).

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

@@ -354,7 +354,7 @@ Signals the completion of a processing step.
 
 ### raw
 
-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.
+Contains raw data from the provider, including content types Mastra doesn't recognize, which are emitted as `raw` chunks rather than discarded. Raw chunks only appear when `includeRawChunks` is enabled.
 
 **type** (`"raw"`): Chunk type identifier
 

package/.docs/reference/tools/isolated-vm-transport.md

@@ -38,7 +38,7 @@ bun add @mastra/isolated-vm
 
 `isolated-vm` is a native addon. It provides prebuilt binaries for common platforms, so installation usually needs no extra setup. A C++ toolchain is only needed on platforms without a matching prebuild, where it falls back to compiling from source.
 
-On Node.js 20 and later, the host process must be started with the `--no-node-snapshot` flag, otherwise creating an isolate crashes the process. The constructor throws an error when the flag is missing. Pass the flag when starting your server, or set it through `NODE_OPTIONS`:
+On Node.js 20 and later, creating an isolate crashes unless the host process starts with `--no-node-snapshot`. The constructor reports the missing flag as an error. Pass it when starting the server or through `NODE_OPTIONS`:
 
 ```bash
 NODE_OPTIONS=--no-node-snapshot npm run dev

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

@@ -349,7 +349,7 @@ console.log(instructionsByServer.db)
 
 ### `authenticate()`
 
-Runs the interactive OAuth authorization-code flow for a server configured with an `MCPOAuthClientProvider` whose redirect URL points at a loopback address. Starts a local callback server, delivers the authorization URL through the provider's `onRedirectToAuthorization` callback, waits for the browser to return the authorization code, exchanges it for tokens, and reconnects. See [Interactive browser authentication](#interactive-browser-authentication).
+Runs the interactive OAuth authorization-code flow for a server whose `MCPOAuthClientProvider` uses a loopback redirect URL. A local callback server passes the authorization URL to the provider's `onRedirectToAuthorization` callback and waits for the browser to return the code. It then exchanges the code for tokens and reconnects. See [Interactive browser authentication](#interactive-browser-authentication).
 
 The optional `timeoutMs` bounds how long the flow waits for the browser to return the authorization code before rejecting, and defaults to 5 minutes.
 
@@ -1056,7 +1056,7 @@ try {
 
 Concurrent `authenticate()` calls for the same server join the pending flow. Different servers authenticate independently. With valid stored tokens the call reconnects without opening a browser.
 
-Hosts that drive the flow themselves can capture the authorization code with the exported `createOAuthCallbackServer` helper, which binds a one-shot loopback server and validates the OAuth `state` parameter before resolving with the code. It creates a plain HTTP server, so it's only for local loopback redirects. Web applications that use an HTTPS redirect URL must host their own callback endpoint and drive the provider directly rather than using this helper:
+Hosts that drive the flow can capture the authorization code with the exported `createOAuthCallbackServer` helper. It creates a one-shot loopback server that validates the OAuth `state` parameter before resolving with the code. Because the server uses plain HTTP, use it only for local loopback redirects. Web applications with an HTTPS redirect URL must host their own callback endpoint and drive the provider directly:
 
 ```typescript
 import { createOAuthCallbackServer, getCallbackUrlCandidates } from '@mastra/mcp'

package/.docs/reference/vectors/couchbase.md

@@ -216,7 +216,7 @@ try {
 
 - **Index Deletion Caveat:** Deleting a Search index doesn't delete the vectors/documents in the associated Couchbase collection. Data remains unless explicitly removed.
 - **Required Permissions:** The Couchbase user must have permissions to connect, read/write documents in the target collection (`kv` role), and manage Search Indexes (`search_admin` role on the relevant bucket/scope).
-- **Index Definition Details & Document Structure:** The `createIndex` method constructs a Search Index definition that indexes the `embedding` field (as type `vector`) and the `content` field (as type `text`), targeting documents within the specified `scopeName.collectionName`. Each document stores the vector in the `embedding` field and metadata in the `metadata` field. If `metadata` contains a `text` property, its value is also copied to a top-level `content` field, which is indexed for text search.
+- **Index Definition Details & Document Structure:** The `createIndex` method builds a Search Index definition for documents in `scopeName.collectionName`. It indexes the `embedding` field as a vector and the `content` field as text. Each document stores its vector in `embedding`, with metadata kept in `metadata`. A `text` property within `metadata` is also copied to the top-level `content` field for text search.
 - **Replication & Durability:** Consider using Couchbase's built-in replication and persistence features for data durability. Monitor index statistics regularly to ensure efficient search.
 
 ## Limitations

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

@@ -222,7 +222,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 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).
+Runs a hybrid search that fuses vector similarity with full-text results through MongoDB's server-side `$rankFusion`. The feature requires MongoDB 8.0 or later and is generally available from 8.1. MongoDB Atlas 8.0.x supports it where enabled, although enablement may require a support case. A full-text search index must exist. Managed indexes create one automatically, while bring-your-own collections require an explicit `createSearchIndex()` call.
 
 **indexName** (`string`): Name of the Mastra index to search
 
@@ -255,7 +255,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 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.
+`hybridQuery()` requires MongoDB 8.0 or later for the `$rankFusion` stage, which is generally available from 8.1. On 8.0.x, the stage runs where enabled, including MongoDB Atlas, but enablement may require a support case. If your deployment is older or lacks `$rankFusion`, run `query()` and `textQuery()` separately before merging the results client-side.
 
 ### `describeIndex()`
 

package/.docs/reference/voice/overview.md

@@ -1090,7 +1090,7 @@ const voice = new CompositeVoice({
   output: elevenlabs.speech('eleven_turbo_v2'), // AI SDK speech
 })
 
-// Works seamlessly with your agent
+// Works directly with your agent
 const voiceAgent = new Agent({
   id: 'aisdk-voice-agent',
   name: 'AI SDK Voice Agent',

package/.docs/reference/workflows/workflow-methods/agent.md

@@ -12,9 +12,9 @@ Unlike wrapping an agent with `createStep()`, `.agent()` records a declarative e
 
 ```typescript
 workflow
-  .map({ prompt: mapVariable({ initData: workflow, path: "topic" }) })
+  .map({ prompt: mapVariable({ initData: workflow, path: 'topic' }) })
   .agent(testAgent)
-  .commit();
+  .commit()
 ```
 
 ## Parameters
@@ -42,7 +42,7 @@ workflow
       }),
     },
   })
-  .commit();
+  .commit()
 ```
 
 ## Referencing an agent by ID
@@ -50,7 +50,7 @@ workflow
 Pass a string to reference a registered agent without importing it. The agent must be registered on the Mastra instance when the workflow runs:
 
 ```typescript
-workflow.agent("test-agent", { maxSteps: 3 }).commit();
+workflow.agent('test-agent', { maxSteps: 3 }).commit()
 ```
 
 ## Persisting agent steps

package/.docs/reference/workflows/workflow-methods/foreach.md

@@ -26,7 +26,7 @@ workflow.foreach(step1, { concurrency: 2 })
 
 ### Execution and waiting
 
-The `.foreach()` method processes all items before the next step executes. The step following `.foreach()` only runs after every iteration has completed, regardless of concurrency settings. With `concurrency: 1` (default), items process sequentially. With higher concurrency, items process in parallel batches, but the next step still waits for all batches to finish.
+The `.foreach()` method processes every item before the next step executes, regardless of concurrency settings. The default `concurrency: 1` processes items sequentially. Higher values use parallel batches, but the next step still waits for every batch to finish.
 
 If you need to run multiple operations per item, use a nested workflow as the step. This keeps all operations for each item together and is cleaner than chaining multiple `.foreach()` calls. See [Nested workflows inside foreach](https://mastra.ai/docs/workflows/control-flow) for examples.
 

package/.docs/reference/workflows/workflow-methods/tool.md

@@ -11,7 +11,7 @@ Unlike wrapping a tool with `createStep()`, `.tool()` records a declarative entr
 ## Usage example
 
 ```typescript
-workflow.tool(testTool).commit();
+workflow.tool(testTool).commit()
 ```
 
 ## Parameters
@@ -31,7 +31,7 @@ workflow.tool(testTool).commit();
 Pass a string to reference a registered tool without importing it. The tool must be registered on the Mastra instance when the workflow runs:
 
 ```typescript
-workflow.tool("lookup-customer", { retries: 2 }).commit();
+workflow.tool('lookup-customer', { retries: 2 }).commit()
 ```
 
 ## Persisting tool steps

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

@@ -175,9 +175,11 @@ await sandbox.start()
 
 `createRepoTemplate()` accepts the same `cpuCount` and `memoryMB` sizing as the `Template()` builder methods, as plain options. They carry the identity and stale-fallback semantics described above. Omit them for the provider defaults.
 
-`getRepositoryAccess` mirrors the resolver a Factory sandbox context carries, so a host can pass its context straight through; when it's absent, `createRepoTemplate()` returns `undefined` and the sandbox boots the provider default. The resolver doesn't run when `PlatformSandbox` reattaches to an existing `sandboxId`. It resolves the repository's default-branch head at fresh-start time, then Platform starts or reuses the corresponding template build. If the repository head can't be resolved or the provider build fails, sandbox creation continues with the provider's default template so runtime setup can perform a cold checkout. For private repositories, the short-lived authorization token is sent as an ephemeral build environment value that stays out of the serialized definition and the persisted template record. It has no effect on content identity.
+`setupCommand` also accepts an array. Each entry runs as its own cached build step. `workingDirectory` sets the cwd for the build and the sandbox, and the repository is cloned to `<workingDirectory>/<repo>`. `buildEnv` passes environment variables to the build steps only. They never enter the serialized definition.
 
-`createRepoTemplate()` also attaches a commit-independent `family` key (`repo:<cloneUrl>:<workdir>`, with the workdir derived from the clone URL) to the definition. `family` groups successive builds of the "same thing", so every commit of the same repository belongs to the same family. Platform uses it to find a prior ready build in the same family and boot the new commit on that warm filesystem while the exact commit template builds in the background. For E2B, stale lookup is also partitioned by the effective CPU and memory settings so a fallback can't silently change the requested machine size. Callers using the raw `Template()` builder can attach their own family key with `.withFamily(key)` (any non-empty string up to 200 characters). Omit it to opt out of family fallback. The family key never influences the content-addressed template identity: two definitions that differ only in `family` share the same cache slot.
+`getRepositoryAccess` mirrors the resolver a Factory sandbox context carries, so a host can pass its context straight through; when it's absent, `createRepoTemplate()` returns `undefined` and the sandbox boots the provider default. The resolver skips reattachment to an existing `sandboxId`; on a fresh start, it resolves the repository's default-branch head before Platform starts or reuses the corresponding template build. If the repository head can't be resolved or the provider build fails, sandbox creation continues with the provider's default template so runtime setup can perform a cold checkout. For private repositories, the short-lived authorization token is sent as an ephemeral build environment value that stays out of the serialized definition and the persisted template record. It has no effect on content identity.
+
+`createRepoTemplate()` also attaches a commit-independent `family` key (`repo:<cloneUrl>:<workingDirectory>/<repo>`) to the definition. `family` groups successive builds of the "same thing", so every commit of the same repository belongs to the same family. Platform uses it to find a prior ready build in the same family and boot the new commit on that warm filesystem while the exact commit template builds in the background. For E2B, stale lookup is also partitioned by the effective CPU and memory settings so a fallback can't silently change the requested machine size. Callers using the raw `Template()` builder can attach their own family key with `.withFamily(key)` (any non-empty string up to 200 characters). Omit it to opt out of family fallback. The family key never influences the content-addressed template identity: two definitions that differ only in `family` share the same cache slot.
 
 Platform stores build state under the definition's server-derived content hash within the selected environment and provider.
 
@@ -289,6 +291,8 @@ console.log(result.exitCode)
 
 **env** (`Record<string, string>`): Environment variables baked into the sandbox at creation time. Per-command environment variables can also be passed to executeCommand.
 
+**workingDirectory** (`string`): Default directory for command execution when no per-command cwd is given. A per-command cwd always wins. Use an absolute path.
+
 **timeout** (`number`): Default command execution timeout in milliseconds. Overridable per call via ExecuteCommandOptions.timeout.
 
 **instructions** (`string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)`): Custom instructions returned by getInstructions(). A string fully replaces the defaults; a function receives the defaults and can extend or customize them per-request.

package/.docs/reference/workspace/process-manager.md

@@ -60,7 +60,7 @@ const handle = await sandbox.processes.spawn('npm run dev', {
 
 **options.env** (`NodeJS.ProcessEnv`): Environment variables for the process.
 
-**options.cwd** (`string`): Working directory for the process.
+**options.cwd** (`string`): Working directory for the process. Defaults to the sandbox's configured workingDirectory, then the provider default.
 
 **options.onStdout** (`(data: string) => void`): Callback for stdout chunks. Called as data arrives.
 

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

@@ -41,7 +41,7 @@ Provider implementations plug into the start lifecycle at one of three rungs; th
 2. **`start()` override returning `SandboxStartResult`**: for providers whose API is a fused get-or-create where decomposition would add round-trips (`PlatformSandbox`, `RailwaySandbox`).
 3. **`start()` override returning `void`**: legacy providers, where the outcome is unknown.
 
-Concurrent `start()` calls on one instance coalesce onto a single in-flight attempt, and joined callers share that attempt's result (all observe `outcome: 'created'` when the shared attempt created the VM). The in-flight slot is cleared when the attempt settles, so a failed start can be retried. While the sandbox is already `running`, `start()` resolves `{ outcome: 'connected' }` without re-invoking the provider.
+Concurrent `start()` calls on one instance coalesce onto a single in-flight attempt, and joined callers share that attempt's result (all observe `outcome: 'created'` when the shared attempt created the VM). The in-flight slot is cleared when the attempt settles, so a failed start can be retried. For a sandbox already in the `running` state, `start()` resolves `{ outcome: 'connected' }` without re-invoking the provider.
 
 The result is also forwarded to the `onStart` lifecycle hook as `{ sandbox, outcome }`.
 
@@ -94,6 +94,23 @@ Semantics:
 - Each call wraps the current hook, so attach once per sandbox instance. Attaching on a path that runs per request stacks duplicate work on every start.
 - Only starts that begin after the call see the new hook.
 
+### `workingDirectory` (constructor option)
+
+Sets the default directory for command execution and process spawns. When a command provides no per-command `cwd`, the sandbox runs it from this directory. A per-command `cwd` always wins. When neither is provided, each provider keeps its own default (E2B home, Docker `/workspace`, Vercel serverless `/tmp`, and so on).
+
+```typescript
+const sandbox = new E2BSandbox({ workingDirectory: '/home/user/my-repo' })
+await sandbox.executeCommand('pwd') // /home/user/my-repo
+await sandbox.executeCommand('pwd', [], { cwd: '/tmp' }) // /tmp
+```
+
+The effective value is readable through the `sandbox.workingDirectory` getter. Providers that compute their value, such as Daytona's automatic probe or Docker's `/workspace` default, report the effective directory through the same getter.
+
+Semantics:
+
+- The value passes to the provider as-is, and the sandbox doesn't create the directory. Absolute paths are recommended: `~`-prefixed paths only work where the provider documents expansion.
+- Some providers keep earlier option names as deprecated aliases feeding the same field: `workingDir` on Docker and Apple container, `workdir` on Modal. When both the alias and `workingDirectory` are set, `workingDirectory` wins.
+
 ### `stop()`
 
 Stop the sandbox.
@@ -139,7 +156,7 @@ const result = await sandbox.executeCommand('npm', ['install', 'lodash'])
 
 **options.timeout** (`number`): Execution timeout in milliseconds
 
-**options.cwd** (`string`): Working directory for the command
+**options.cwd** (`string`): Working directory for this command. Defaults to the sandbox's configured workingDirectory, then the provider default.
 
 **options.env** (`Record<string, string>`): Additional environment variables for this command. These take precedence over the sandbox environment for this command execution only.
 
@@ -167,7 +184,7 @@ The runtime environment applies to commands executed through the sandbox rather
 
 ### `getEnv()`
 
-Returns a copy of the sandbox's current runtime environment. Mutating the returned object doesn't change the sandbox, so use `setEnv()` for updates.
+Returns a copy of the sandbox's current runtime environment; because mutations to the returned object don't change the sandbox, use `setEnv()` for updates.
 
 ```typescript
 const token = sandbox.getEnv().GH_TOKEN

package/.docs/reference/workspace/workspace-class.md

@@ -243,7 +243,7 @@ Stop the workspace's live resources without destroying them.
 await workspace.stop()
 ```
 
-`stop()` shuts down language servers and closes the browser, then stops the sandbox provider. Remote sandbox providers suspend or pause the sandbox so it can resume later. `LocalSandbox` kills its background processes and unmounts filesystems. Stopping isn't a teardown. The filesystem, search index, and skills keep working, and the next sandbox operation starts the sandbox again.
+`stop()` shuts down language servers and the browser before stopping the sandbox provider. Remote providers suspend or pause the sandbox for later resumption, while `LocalSandbox` kills background processes and unmounts filesystems. Stopping isn't a teardown. The filesystem and search index remain available along with skills, and the next sandbox operation starts the sandbox again.
 
 `mastra.shutdown()` calls `stop()` for registered workspaces, so a process restart suspends remote sandboxes instead of deleting them. To fully tear a workspace down, call `destroy()` or `mastra.removeWorkspace(id, { destroy: true })` explicitly.
 
@@ -390,7 +390,7 @@ if (workspace.hasFilesystemConfig()) {
 
 #### `resolveFilesystem({ requestContext })`
 
-Resolve the filesystem for a request context. When a resolver function is configured, calls it with the provided `requestContext`. When a static filesystem is configured, returns it directly. Returns `undefined` if no filesystem is configured.
+Resolve the filesystem for a request context by calling a configured resolver with `requestContext` or returning a configured static filesystem directly. Returns `undefined` when no filesystem is configured.
 
 ```typescript
 import { RequestContext } from '@mastra/core/request-context'
@@ -421,7 +421,7 @@ if (workspace.hasSandboxConfig()) {
 
 #### `resolveSandbox({ requestContext })`
 
-Resolve the sandbox for a request context. When a resolver function is configured, calls it with the provided `requestContext`. When a static sandbox is configured, returns it directly. Returns `undefined` if no sandbox is configured.
+Resolve the sandbox for a request context by calling a configured resolver with `requestContext` or returning a configured static sandbox directly. Returns `undefined` when no sandbox is configured.
 
 ```typescript
 import { RequestContext } from '@mastra/core/request-context'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.23-alpha.1",
+  "version": "1.2.23-alpha.10",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -8,8 +8,7 @@
   "files": [
     "dist",
     ".docs",
-    "README.md",
-    "CHANGELOG.md"
+    "README.md"
   ],
   "exports": {
     ".": {
@@ -28,8 +27,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.63.3-alpha.0",
-    "@mastra/mcp": "^1.17.2"
+    "@mastra/core": "1.64.0-alpha.4",
+    "@mastra/mcp": "^1.17.3-alpha.0"
   },
   "devDependencies": {
     "@hono/node-server": "^2.0.0",
@@ -45,8 +44,8 @@
     "tsx": "^4.23.1",
     "typescript": "^7.0.2",
     "vitest": "4.1.10",
-    "@mastra/core": "1.63.3-alpha.0",
     "@internal/lint": "0.0.129",
+    "@mastra/core": "1.64.0-alpha.4",
     "@internal/types-builder": "0.0.104"
   },
   "homepage": "https://mastra.ai",