@mastra/mcp-docs-server 1.1.46-alpha.2 → 1.1.46-alpha.4

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

@@ -62,7 +62,7 @@ Internally, `streamUntilIdle()`:
 
 1. Runs the initial turn via `agent.stream(...)` and pipes its `fullStream` into the outer stream.
 2. Subscribes to background-task completion events for the resolved memory scope.
-3. Queues each terminal event (`background-task-completed`, `background-task-failed`, `background-task-cancelled`) and, when the outer wrapper is idle between turns, re-invokes `agent.stream([], ...)` with a directive listing the just-completed `toolCallId`s. The continuation turn flows into the same outer stream.
+3. Queues each terminal event (`background-task-completed`, `background-task-failed`, `background-task-cancelled`) and, when the outer wrapper is idle between turns, re-invokes `agent.stream([], ...)` with a directive listing the completed `toolCallId`s. The continuation turn flows into the same outer stream.
 4. Closes the outer stream once no tasks are running and no completions are queued.
 
 ## Extended usage example

package/.docs/reference/tools/brightdata.md

@@ -155,9 +155,9 @@ const agent = new Agent({
 
 ## Environment variables
 
-| Variable               | Description                                                                                        |
-| ---------------------- | -------------------------------------------------------------------------------------------------- |
-| `BRIGHTDATA_API_TOKEN` | Your Bright Data API token. Used as the default when `apiKey` is not passed to a factory function. |
+| Variable               | Description                                                                                       |
+| ---------------------- | ------------------------------------------------------------------------------------------------- |
+| `BRIGHTDATA_API_TOKEN` | Your Bright Data API token. Used as the default when `apiKey` isn't passed to a factory function. |
 
 ## Related
 

package/.docs/reference/tools/create-code-mode.md

@@ -0,0 +1,124 @@
+# createCodeMode()
+
+**Added in:** `@mastra/core@1.38.0`
+
+The `createCodeMode()` function returns a tool and generated instructions that let an agent run multi-tool computations as one TypeScript function. The generated code runs in a workspace sandbox, and each `external_*` call runs the real tool on the host with validation, request context, and tracing.
+
+For a conceptual overview, see [Code mode](https://mastra.ai/docs/agents/code-mode).
+
+## Usage example
+
+Create a code mode tool, add its generated instructions to the agent, and register the returned tool with the same id.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createCodeMode, createTool } from '@mastra/core/tools'
+import { LocalSandbox } from '@mastra/core/workspace'
+import { z } from 'zod'
+
+const getTopProducts = createTool({
+  id: 'getTopProducts',
+  description: 'Get top selling products',
+  inputSchema: z.object({ limit: z.number() }),
+  outputSchema: z.object({
+    products: z.array(z.object({ id: z.string(), name: z.string(), totalSales: z.number() })),
+  }),
+  execute: async ({ limit }) => fetchTopProducts(limit),
+})
+
+const getProductRatings = createTool({
+  id: 'getProductRatings',
+  description: 'Get ratings for a product',
+  inputSchema: z.object({ productId: z.string() }),
+  outputSchema: z.object({ ratings: z.array(z.object({ score: z.number() })) }),
+  execute: async ({ productId }) => fetchRatings(productId),
+})
+
+const { tool, instructions } = createCodeMode({
+  tools: { getTopProducts, getProductRatings },
+  sandbox: new LocalSandbox(),
+})
+
+export const shopAgent = new Agent({
+  name: 'shop-assistant',
+  instructions: ['You are a helpful shopping assistant.', instructions],
+  model: 'openai/gpt-5.5',
+  tools: { execute_typescript: tool },
+})
+```
+
+## Parameters
+
+**config** (`CodeModeConfig`): Configuration for the code mode tool and generated instructions.
+
+**config.tools** (`ToolsInput`): Tools exposed to the generated code as \`external\_\<id>\` functions. Only these tools can be called.
+
+**config.sandbox** (`WorkspaceSandbox`): Sandbox used to execute the generated code. Required unless the agent runs in a workspace that provides a sandbox. Pass \`new LocalSandbox()\` to run on the host explicitly.
+
+**config.timeout** (`number`): Execution timeout in milliseconds.
+
+**config.id** (`string`): The generated tool id.
+
+**transport** (`CodeModeTransport`): Optional transport implementation used to run the generated code in the sandbox. The default transport uses stdio JSON-RPC over the workspace sandbox process API.
+
+## Returns
+
+Returns a `CodeModeResult` object.
+
+**tool** (`Tool<any, any>`): The generated code mode tool. By default, its id is \`execute\_typescript\`.
+
+**instructions** (`string`): Generated model instructions with typed \`external\_\*\` declarations for the configured tools.
+
+## CodeModeToolResult
+
+The generated tool returns a `CodeModeToolResult`.
+
+**success** (`boolean`): Whether the generated code ran to completion without throwing.
+
+**result** (`unknown`): The value returned by the generated code.
+
+**logs** (`string[]`): Captured console output from \`console.log\`, \`console.info\`, \`console.warn\`, and \`console.error\`, in order.
+
+**error** (`{ message: string; name?: string; line?: number }`): Error details when the generated code throws or fails to execute.
+
+**error.message** (`string`): Error message.
+
+**error.name** (`string`): Error name, when available.
+
+**error.line** (`number`): Line number associated with the failure, when available.
+
+## Inspecting instructions
+
+Use `createCodeModeInstructions()` to inspect the exact prompt content generated for a set of tools.
+
+```typescript
+import { createCodeModeInstructions } from '@mastra/core/tools'
+
+console.log(
+  createCodeModeInstructions({
+    tools: { getTopProducts, getProductRatings },
+  }),
+)
+```
+
+The instructions include the usage contract and one typed `declare function external_<id>(...)` line for each configured tool. Tool ids are sanitized into valid TypeScript function names, and conflicting sanitized names throw an error.
+
+## createCodeModeTool()
+
+Use `createCodeModeTool()` when you only need the tool and want to manage instructions separately. Most agents should use `createCodeMode()` so the tool and matching instructions stay together.
+
+```typescript
+import { createCodeModeTool } from '@mastra/core/tools'
+import { LocalSandbox } from '@mastra/core/workspace'
+
+export const codeModeTool = createCodeModeTool({
+  tools: { getTopProducts, getProductRatings },
+  sandbox: new LocalSandbox(),
+})
+```
+
+## Related
+
+- [Code mode](https://mastra.ai/docs/agents/code-mode)
+- [createTool()](https://mastra.ai/reference/tools/create-tool)
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)

package/.docs/reference/tools/create-tool.md

@@ -125,7 +125,7 @@ export const weatherTool = createTool({
 })
 ```
 
-Mastra forwards `strict: true` to model adapters that support strict tool calling. On adapters that do not support strict tool calling, Mastra ignores this option.
+Mastra forwards `strict: true` to model adapters that support strict tool calling. On adapters that don't support strict tool calling, Mastra ignores this option.
 
 ## Example with `toModelOutput`
 

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

@@ -153,7 +153,7 @@ const agent = new Agent({
 })
 ```
 
-When `forwardInstructions` is omitted (the default), instructions are still cached and can be inspected via [`getServerInstructions()`](#getserverinstructions), but are not added to any agent's system prompt.
+When `forwardInstructions` is omitted (the default), instructions are still cached and can be inspected via [`getServerInstructions()`](#getserverinstructions), but aren't added to any agent's system prompt.
 
 > **Security note:** server instructions are forwarded verbatim (subject only to length truncation) into the agent's system prompt. A malicious or compromised MCP server can use them to inject instructions the agent will treat as trusted system guidance. Only enable `forwardInstructions` for servers you trust, and prefer reviewing instructions with `getServerInstructions()` before forwarding instructions from third-party servers.
 
@@ -179,7 +179,7 @@ const res = await agent.stream(prompt, {
 
 ### `getServerInstructions()`
 
-Returns the instructions currently known for each configured MCP server. Servers that have not connected yet, or do not advertise instructions, return `undefined`.
+Returns the instructions currently known for each configured MCP server. Servers that haven't connected yet, or don't advertise instructions, return `undefined`.
 
 ```typescript
 getServerInstructions(): Record<string, string | undefined>
@@ -1065,9 +1065,9 @@ await agent.generate('Hello!', {
 
 ## Handling auth failures inside custom fetch
 
-A custom `fetch` should not `throw` when authentication is unavailable. The Streamable HTTP transport in the MCP SDK opens a long-lived `GET /mcp` "standalone listener" stream in the background to receive server-pushed notifications. Errors on that stream are retried with exponential backoff, and a thrown `fetch` or a cleanly-closed stream can produce an indefinite reconnect loop at roughly one attempt per second.
+A custom `fetch` shouldn't `throw` when authentication is unavailable. The Streamable HTTP transport in the MCP SDK opens a long-lived `GET /mcp` "standalone listener" stream in the background to receive server-pushed notifications. Errors on that stream are retried with exponential backoff, and a thrown `fetch` or a cleanly-closed stream can produce an indefinite reconnect loop at roughly one attempt per second.
 
-Return a synthetic `Response` instead. The [MCP Streamable HTTP specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports) defines `405 Method Not Allowed` as the signal a server returns when it does not offer the GET SSE stream, and the SDK honors it as a terminal status that stops the listener cleanly. Use this to disable the listener when your server does not push notifications.
+Return a synthetic `Response` instead. The [MCP Streamable HTTP specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports) defines `405 Method Not Allowed` as the signal a server returns when it doesn't offer the GET SSE stream, and the SDK honors it as a terminal status that stops the listener cleanly. Use this to disable the listener when your server doesn't push notifications.
 
 The following pattern waits for an auth token on POST requests, attaches it to outgoing headers, and short-circuits the GET listener with a synthetic 405:
 
@@ -1108,7 +1108,7 @@ const mcpClient = new MCPClient({
 })
 ```
 
-Return `405` for the GET listener only when your server does not push notifications back to the client. If your server uses the standalone GET stream, attach the auth token on `GET` requests as well and let the request through.
+Return `405` for the GET listener only when your server doesn't push notifications back to the client. If your server uses the standalone GET stream, attach the auth token on `GET` requests as well and let the request through.
 
 ## Using SSE request headers
 

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

@@ -69,6 +69,8 @@ The constructor accepts an `MCPServerConfig` object with the following propertie
 
 **mapAuthInfoToUser** (`({ authInfo, extra, requestContext }) => unknown | null | undefined | Promise<unknown | null | undefined>`): Maps MCP transport auth data from \`extra.authInfo\` into the \`user\` value used by Mastra FGA checks. Use this when an OAuth-protected MCP server is registered on a Mastra instance with an FGA provider.
 
+**fga** (`{ resourceMapping?: Partial<Record<'tool' | 'tools', { fgaResourceType: string; deriveId?: ({ user, resourceId, requestContext }) => string | undefined }>>; permissionMapping?: Record<string, string> }`): Overrides resource and permission mappings for this MCP server's \`tools/list\` and \`tools/call\` FGA checks. Use this when MCP authorization should be scoped differently from internal agent or workflow tool execution.
+
 **repository** (`Repository`): Optional repository information for the server's source code.
 
 **releaseDate** (`string`): Optional release date of this server version (ISO 8601 string). Defaults to the time of instantiation if not provided.
@@ -1129,6 +1131,49 @@ const server = new MCPServer({
 })
 ```
 
+### Scope MCP tool FGA separately
+
+Use `fga.resourceMapping` and `fga.permissionMapping` when MCP clients need a different authorization scope than internal agent or workflow tool execution. The override applies only to `tools/list` and `tools/call` checks for this MCP server.
+
+```typescript
+import { MastraFGAPermissions } from '@mastra/core/auth/ee'
+
+const server = new MCPServer({
+  id: 'my-server',
+  name: 'My Server',
+  version: '1.0.0',
+  tools: { getUserData },
+  mapAuthInfoToUser: ({ authInfo }) => {
+    const user = authInfo as {
+      extra?: {
+        userId?: string
+        organizationMembershipId?: string
+      }
+    }
+
+    if (!user.extra?.userId) {
+      return null
+    }
+
+    return {
+      id: user.extra.userId,
+      organizationMembershipId: user.extra.organizationMembershipId,
+    }
+  },
+  fga: {
+    resourceMapping: {
+      tool: {
+        fgaResourceType: 'user',
+        deriveId: ({ user }) => (user as { id: string }).id,
+      },
+    },
+    permissionMapping: {
+      [MastraFGAPermissions.TOOLS_EXECUTE]: 'read',
+    },
+  },
+})
+```
+
 ### Setting Up Authentication Middleware
 
 To pass data to your tools, populate `req.auth` on the Node.js request object in your HTTP server middleware before calling `server.startHTTP()`.

package/.docs/reference/tools/perplexity.md

@@ -139,10 +139,10 @@ const agent = new Agent({
 
 ## Environment variables
 
-| Variable             | Description                                                                                     |
-| -------------------- | ----------------------------------------------------------------------------------------------- |
-| `PERPLEXITY_API_KEY` | Your Perplexity API key. Used as the default when `apiKey` is not passed to a factory function. |
-| `PPLX_API_KEY`       | Fallback used when `PERPLEXITY_API_KEY` is unset.                                               |
+| Variable             | Description                                                                                    |
+| -------------------- | ---------------------------------------------------------------------------------------------- |
+| `PERPLEXITY_API_KEY` | Your Perplexity API key. Used as the default when `apiKey` isn't passed to a factory function. |
+| `PPLX_API_KEY`       | Fallback used when `PERPLEXITY_API_KEY` is unset.                                              |
 
 ## Related
 

package/.docs/reference/tools/tavily.md

@@ -295,9 +295,9 @@ const agent = new Agent({
 
 ## Environment variables
 
-| Variable         | Description                                                                                 |
-| ---------------- | ------------------------------------------------------------------------------------------- |
-| `TAVILY_API_KEY` | Your Tavily API key. Used as the default when `apiKey` is not passed to a factory function. |
+| Variable         | Description                                                                                |
+| ---------------- | ------------------------------------------------------------------------------------------ |
+| `TAVILY_API_KEY` | Your Tavily API key. Used as the default when `apiKey` isn't passed to a factory function. |
 
 ## Related
 

package/.docs/reference/voice/aws-nova-sonic.md

@@ -150,7 +150,7 @@ Returns: `Promise<void>`
 
 ### `endAudioInput()`
 
-Signals the end of the current audio turn so the model can finalize its response. Call this when the user stops speaking and the provider is not configured for server-side turn detection.
+Signals the end of the current audio turn so the model can finalize its response. Call this when the user stops speaking and the provider isn't configured for server-side turn detection.
 
 Returns: `Promise<void>`
 

package/.docs/reference/voice/google-gemini-live.md

@@ -265,7 +265,7 @@ Native-audio Gemini Live models — any model whose ID contains `native-audio`,
 - The model's spoken reply is delivered as audio plus an `output_audio_transcription` transcript and surfaced as `writing` with `role: 'assistant'`.
 - The model's internal reasoning is delivered as `modelTurn.parts.text` and surfaced as `thinking`.
 
-On non-native-audio models there is no `output_audio_transcription` channel, so `modelTurn.parts.text` is the spoken response itself and is emitted as `writing`; the `thinking` event does not fire.
+On non-native-audio models there is no `output_audio_transcription` channel, so `modelTurn.parts.text` is the spoken response itself and is emitted as `writing`; the `thinking` event doesn't fire.
 
 Input transcription, output transcription, and barge-in detection (`realtime_input_config.activity_handling = 'START_OF_ACTIVITY_INTERRUPTS'`) are enabled automatically in the setup payload — no extra configuration is required.
 

package/.docs/reference/voice/inworld-realtime.md

@@ -54,7 +54,7 @@ await voice.send(microphoneStream)
 voice.close()
 ```
 
-> Inworld API keys ship pre-Basic-encoded. Paste them verbatim into `INWORLD_API_KEY`; the package does not re-encode them.
+> Inworld API keys ship pre-Basic-encoded. Paste them verbatim into `INWORLD_API_KEY`; the package doesn't re-encode them.
 
 ## Constructor parameters
 
@@ -116,7 +116,7 @@ Use the typed `session` field for documented Inworld realtime options. Fields co
 
 ### `providerData` (Inworld extensions)
 
-`providerData` is a typed object for Inworld-specific realtime extensions. It is sent under `session.providerData` on every `session.update`, and composes with any `session.providerData` you set via the `session` field — the constructor `providerData` wins on key collisions.
+`providerData` is a typed object for Inworld-specific realtime extensions. It's sent under `session.providerData` on every `session.update`, and composes with any `session.providerData` you set via the `session` field — the constructor `providerData` wins on key collisions.
 
 It has five branches plus two session-level fields:
 
@@ -342,12 +342,12 @@ Any voice ID from [Inworld's voice catalog](https://docs.inworld.ai/quickstart-t
 
 ## Notes
 
-- API keys can be provided via constructor options or the `INWORLD_API_KEY` environment variable. Keys are pre-Basic-encoded; do not re-encode them.
+- API keys can be provided via constructor options or the `INWORLD_API_KEY` environment variable. Keys are pre-Basic-encoded; don't re-encode them.
 - The WebSocket URL appends `?key=<sessionId>&protocol=realtime`. The model is configured via the initial `session.update`, not the URL.
-- Per-call `speak(input, { speaker })` scopes the voice override to a single response (via the flat `response.voice` field) and does NOT mutate the session.
+- Per-call `speak(input, { speaker })` scopes the voice override to a single response (via the flat `response.voice` field) and doesn't mutate the session.
 - Audio output defaults to PCM16 at 24 kHz. Telephony `audio/pcmu` and `audio/pcma` at 8 kHz, and `audio/float32`, are also supported via `session.audio.output.format`.
 - Use `connect()` before any send, speak, or listen call. Events sent before the WebSocket is open are queued and flushed once the server acknowledges `session.updated`.
 - The voice instance must be closed with `close()` or `disconnect()` to release the WebSocket.
-- `audio.input.turn_detection` defaults to semantic VAD when `session` does not supply it. Override with your own object, or pass `null` to disable turn detection entirely.
+- `audio.input.turn_detection` defaults to semantic VAD when `session` doesn't supply it. Override with your own object, or pass `null` to disable turn detection entirely.
 - `audio.input.transcription` defaults to `{ model: 'inworld/inworld-stt-1' }`, so user-side `writing` events fire out of the box. Override with your own object, or pass `null` to disable user-side transcription.
 - `on()` and `off()` are typed against `InworldVoiceEventMap` — known event names yield a typed callback payload, unknown names fall back to `unknown`.

package/.docs/reference/voice/inworld.md

@@ -130,6 +130,6 @@ const speakers = await voice.getSpeakers()
 ## Notes
 
 - The TTS endpoint uses progressive NDJSON streaming, so audio playback can begin before the full response is received.
-- An API key can be provided via the `speechModel` or `listeningModel` config, or the `INWORLD_API_KEY` environment variable. TTS and STT keys are resolved independently: passing distinct `speechModel.apiKey` and `listeningModel.apiKey` values lets each service use its own credential. If only one is provided, it is reused for both services as a fallback before the env var.
+- An API key can be provided via the `speechModel` or `listeningModel` config, or the `INWORLD_API_KEY` environment variable. TTS and STT keys are resolved independently: passing distinct `speechModel.apiKey` and `listeningModel.apiKey` values lets each service use its own credential. If only one is provided, it's reused for both services as a fallback before the env var.
 - `inworld-tts-2` is the default flagship model. Use `deliveryMode` (`STABLE` | `BALANCED` | `CREATIVE`) to steer delivery style on this model. The `temperature` option is ignored on `inworld-tts-2`.
 - The `inworld-tts-1.5-mini` model offers lower latency at the cost of reduced voice quality compared to `inworld-tts-1.5-max`.

package/.docs/reference/voice/sarvam.md

@@ -127,4 +127,4 @@ Returns: `Promise<Array<{voiceId: SarvamVoiceId}>>`
 - Audio is returned as a stream containing binary audio data
 - Speech recognition supports mp3 and wav audio formats
 - `bulbul:v1`, `saarika:v1`, `saarika:v2`, and `saarika:flash` have been deprecated by Sarvam and are no longer supported. Use `bulbul:v3` (or `bulbul:v2`) for TTS and `saarika:v2.5` (or `saaras:v3`) for STT.
-- Speaker names are not interchangeable between `bulbul:v2` and `bulbul:v3` — each model version has its own speaker catalog.
+- Speaker names aren't interchangeable between `bulbul:v2` and `bulbul:v3` — each model version has its own speaker catalog.

package/.docs/reference/workspace/agentcore-runtime-sandbox.md

@@ -6,7 +6,7 @@ Use `AgentCoreRuntimeSandbox` when your agent already runs in AgentCore Runtime
 
 > **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
 
-> **Warning:** `AgentCoreRuntimeSandbox` only supports one-shot command execution. It does not support background process management, stdin, or filesystem mounts. AgentCore Code Interpreter is a separate AWS service and is not part of this provider.
+> **Warning:** `AgentCoreRuntimeSandbox` only supports one-shot command execution. It doesn't support background process management, stdin, or filesystem mounts. AgentCore Code Interpreter is a separate AWS service and isn't part of this provider.
 
 ## Installation
 
@@ -139,7 +139,7 @@ Returns: `Promise<CommandResult>`.
 
 #### `start()`
 
-Runs the sandbox lifecycle start hook. This provider does not create an AgentCore Runtime session during `start()`.
+Runs the sandbox lifecycle start hook. This provider doesn't create an AgentCore Runtime session during `start()`.
 
 ```typescript
 await sandbox.start()
@@ -157,7 +157,7 @@ await sandbox.stop()
 
 Explicitly stops the AgentCore Runtime session used by this sandbox.
 
-Use this when the sandbox owns the runtime session and you want to clean it up directly. `destroy()` does not call this method unless `stopSessionOnLifecycle` is `true`, because AgentCore Runtime sessions can be shared with agent invocations outside the Workspace sandbox lifecycle.
+Use this when the sandbox owns the runtime session and you want to clean it up directly. `destroy()` doesn't call this method unless `stopSessionOnLifecycle` is `true`, because AgentCore Runtime sessions can be shared with agent invocations outside the Workspace sandbox lifecycle.
 
 ```typescript
 await sandbox.stopRuntimeSession()
@@ -188,10 +188,10 @@ Returns: `Promise<SandboxInfo>`.
 `AgentCoreRuntimeSandbox` follows AgentCore Runtime command execution semantics:
 
 - **One-shot commands**: Each command runs to completion or timeout.
-- **No persistent shell**: Shell state does not carry over between commands. Encode state in each command, for example `cd /workspace && npm test`.
-- **Background processes are not supported**: The provider does not expose a `processes` manager.
-- **Interactive stdin is unavailable**: Runtime command execution does not provide an interactive stdin stream through this provider.
-- **Workspace filesystem mounts are unsupported**: Workspace filesystem mounting is not supported by this provider.
+- **No persistent shell**: Shell state doesn't carry over between commands. Encode state in each command, for example `cd /workspace && npm test`.
+- **Background processes aren't supported**: The provider doesn't expose a `processes` manager.
+- **Interactive stdin is unavailable**: Runtime command execution doesn't provide an interactive stdin stream through this provider.
+- **Workspace filesystem mounts are unsupported**: Workspace filesystem mounting isn't supported by this provider.
 - **Container-dependent tools**: Commands can only use tools installed in the AgentCore Runtime container image.
 
 ## Related

package/.docs/reference/workspace/azure-blob-filesystem.md

@@ -55,7 +55,7 @@ const agent = new Agent({
 
 ### Account key
 
-Use an account name and account key when you do not want to pass a full connection string:
+Use an account name and account key when you don't want to pass a full connection string:
 
 ```typescript
 import { AzureBlobFilesystem } from '@mastra/azure/blob'
@@ -209,7 +209,7 @@ const config = filesystem.getMountConfig()
 // { type: 'azure-blob', container: 'my-container', ... }
 ```
 
-> **Note:** Azure Blob sandbox mounting depends on sandbox support for `azure-blob` mount configs. Use `filesystem` for direct workspace file operations when your sandbox provider does not support Azure Blob mounts.
+> **Note:** Azure Blob sandbox mounting depends on sandbox support for `azure-blob` mount configs. Use `filesystem` for direct workspace file operations when your sandbox provider doesn't support Azure Blob mounts.
 
 ## Related
 

package/.docs/reference/workspace/files-sdk-filesystem.md

@@ -170,10 +170,10 @@ const url = await filesystem.files.url('reports/q3.pdf')
 `FilesSDKFilesystem` treats the configured backend as an object store, even when the underlying adapter is hierarchical (such as `fs`). This keeps behavior consistent across adapters:
 
 - **`mkdir`** is a no-op. Directories exist implicitly when keys with that prefix exist.
-- **`exists`** returns `true` only when an exact key is present as a file, or when the path is a prefix that contains at least one child key. Empty leftover directories on hierarchical adapters do not count.
-- **`deleteFile`** throws `FileNotFoundError` when the key does not exist, unless `{ force: true }` is passed.
+- **`exists`** returns `true` only when an exact key is present as a file, or when the path is a prefix that contains at least one child key. Empty leftover directories on hierarchical adapters don't count.
+- **`deleteFile`** throws `FileNotFoundError` when the key doesn't exist, unless `{ force: true }` is passed.
 - **`deleteFile`** on a directory delegates to `rmdir({ recursive: true })`, matching the [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem) and [`GCSFilesystem`](https://mastra.ai/reference/workspace/gcs-filesystem) behavior.
-- **`moveFile`** is implemented as `copyFile` followed by `deleteFile`. It is **not atomic** — if the source delete fails after a successful copy, the destination remains and the source is not removed.
+- **`moveFile`** is implemented as `copyFile` followed by `deleteFile`. it's **not atomic** — if the source delete fails after a successful copy, the destination remains and the source isn't removed.
 - **`appendFile`** is a read-modify-write operation. Concurrent appends to the same key may overwrite each other; this is inherent to object storage and not specific to FilesSDK.
 - **`readdir({ recursive: true })`** emits intermediate directory entries (for example, `a/b` is emitted alongside `a/b/c.txt`).
 

package/.docs/reference/workspace/google-drive-filesystem.md

@@ -64,7 +64,7 @@ Supply one of the following authentication options:
 
 #### Service account
 
-Service account auth is the recommended option for backend agents. There is no user consent flow and no token refresh handling. You only need **two values** from the service account JSON key file: `client_email` and `private_key`.
+Service account auth is the recommended option for backend agents. No user consent flow and no token refresh handling is required. You only need **two values** from the service account JSON key file: `client_email` and `private_key`.
 
 ##### Set up the service account
 
@@ -76,19 +76,19 @@ Service account auth is the recommended option for backend agents. There is no u
 
 ##### Share the Drive folder with the service account
 
-The service account is its own Google identity. It cannot see anything in Drive until you share with it explicitly.
+The service account is its own Google identity. It can't see anything in Drive until you share with it explicitly.
 
 1. Open the target folder in [Google Drive](https://drive.google.com/).
 2. Select **Share**.
 3. Paste the service account's `client_email` address.
 4. Set the role to **Editor** (for read and write) or **Viewer** (for read-only access). Select **Send**.
-5. Copy the folder ID from the URL. It is the segment after `/folders/` in `https://drive.google.com/drive/folders/<folderId>`.
+5. Copy the folder ID from the URL. it's the segment after `/folders/` in `https://drive.google.com/drive/folders/<folderId>`.
 
-> **Warning:** Service accounts cannot create files in standard "My Drive" folders. A service account has no personal Drive storage quota, so any file it creates needs to be owned by a quota-bearing entity. If you only share a personal Drive folder, read operations work but writes fail with a quota error.
+> **Warning:** Service accounts can't create files in standard "My Drive" folders. A service account has no personal Drive storage quota, so any file it creates needs to be owned by a quota-bearing entity. If you only share a personal Drive folder, read operations work but writes fail with a quota error.
 >
 > For write access, place the folder inside a **shared drive** (formerly Team Drive) and add the service account as a member of that shared drive. Shared drives provide the storage quota that service-account-created files need.
 >
-> Read-only workloads against a personal Drive folder do not have this restriction.
+> Read-only workloads against a personal Drive folder don't have this restriction.
 
 ##### Configure the filesystem
 
@@ -113,13 +113,13 @@ const filesystem = new GoogleDriveFilesystem({
 })
 ```
 
-You do **not** need to copy the entire JSON file or pass other fields like `project_id`, `client_id`, `private_key_id`, or `token_uri`. They are not used. Only `clientEmail` and `privateKey` are required. `privateKeyId`, `scopes`, and `subject` are optional. `scopes` defaults to `['https://www.googleapis.com/auth/drive']`, which is the scope required for the service account to see folders shared with it. The narrower `drive.file` scope only grants access to files the application created itself, so a folder shared with the service account would return `404 Not Found`.
+You **don't** need to copy the entire JSON file or pass other fields like `project_id`, `client_id`, `private_key_id`, or `token_uri`. They're not used. Only `clientEmail` and `privateKey` are required. `privateKeyId`, `scopes`, and `subject` are optional. `scopes` defaults to `['https://www.googleapis.com/auth/drive']`, which is the scope required for the service account to see folders shared with it. The narrower `drive.file` scope only grants access to files the application created itself, so a folder shared with the service account would return `404 Not Found`.
 
 `GoogleDriveFilesystem` automatically normalizes the `privateKey` string before signing. It strips surrounding quotes (including escaped quotes from JSON-wrapped values), converts literal `\n` sequences to real newlines, normalizes `\r\n` line endings, and removes a trailing comma. The key works regardless of how your `.env` loader handles the value.
 
 ##### Troubleshoot
 
-- **`404 File not found: <folderId>`**: The service account does not have access to the folder. Confirm the folder is shared with the exact `client_email` address and that the folder ID matches the URL.
+- **`404 File not found: <folderId>`**: The service account doesn't have access to the folder. Confirm the folder is shared with the exact `client_email` address and that the folder ID matches the URL.
 - **`storageQuotaExceeded` on write**: The folder is in a personal "My Drive". Move the folder to a shared drive and add the service account as a member.
 - **`error:1E08010C:DECODER routines::unsupported`**: The `privateKey` value is malformed. Confirm the value contains the full PEM block and that newlines are preserved (literal `\n` is fine).
 

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

@@ -155,7 +155,7 @@ console.log(result.exitCode)
 await handle.kill()
 ```
 
-> **Note:** `sendStdin()` is not supported — the Modal JS SDK does not expose stdin on `Sandbox.exec()`.
+> **Note:** `sendStdin()` isn't supported — the Modal JS SDK doesn't expose stdin on `Sandbox.exec()`.
 
 See [`SandboxProcessManager` reference](https://mastra.ai/reference/workspace/process-manager) for the full API.