@mastra/mcp-docs-server 1.2.16 → 1.2.17-alpha.3

package/.docs/docs/agents/code-mode.md

@@ -29,7 +29,7 @@ Each turn adds the full tool response to the agent's context window which can le
 
 With code mode, your tools keep running on the host with full validation, request context, and tracing. Only the model's orchestration code runs in the sandbox. Each `external_*` call is bridged back to the real tool on the host, and the function can reduce or aggregate results before returning one response to the agent.
 
-The function runs in a [Workspace sandbox](https://mastra.ai/docs/workspace/overview). A sandbox is required, because code mode runs model-authored code and the execution boundary must be chosen deliberately. Pass one via `sandbox`, or run the agent in a workspace that provides one. To execute on the host machine, pass `new LocalSandbox()` explicitly. This runs the function as a host `node` process with host privileges, so only use it for trusted or local development.
+The function runs in a [Workspace sandbox](https://mastra.ai/docs/workspace/sandbox). A sandbox is required, because code mode runs model-authored code and the execution boundary must be chosen deliberately. Pass one via `sandbox`, or run the agent in a workspace that provides one. To execute on the host machine, pass `new LocalSandbox()` explicitly. This runs the function as a host `node` process with host privileges, so only use it for trusted or local development.
 
 Transports that bring their own execution boundary are the exception: with [`IsolatedVmCodeModeTransport`](https://mastra.ai/reference/tools/isolated-vm-transport) the program runs in an in-process V8 isolate and no sandbox is needed (see [In-process isolation](#in-process-isolation)).
 
@@ -184,4 +184,4 @@ See [Choosing a transport](https://mastra.ai/reference/tools/quickjs-transport)
 - [IsolatedVmCodeModeTransport reference](https://mastra.ai/reference/tools/isolated-vm-transport)
 - [QuickJsCodeModeTransport reference](https://mastra.ai/reference/tools/quickjs-transport)
 - [Tools](https://mastra.ai/docs/agents/using-tools)
-- [Workspace overview](https://mastra.ai/docs/workspace/overview)
+- [Sandbox](https://mastra.ai/docs/workspace/sandbox)

package/.docs/docs/agents/skills.md

@@ -4,7 +4,7 @@
 
 Skills are reusable instructions that teach agents how to perform specific tasks. They follow the [Agent Skills specification](https://agentskills.io).
 
-You can attach skills directly to an agent through its `skills` config, or configure them on a [workspace](https://mastra.ai/docs/workspace/overview). Attach them to the agent when the skills belong to that specific agent and you want to define them in code with no workspace required. Use a workspace when you want skills discovered from the filesystem and shared across every agent that uses it. This page covers the agent-level approach, defining skills in code and loading them from files, plus resolving them per request.
+You can attach skills directly to an agent through its `skills` config, or configure them on a [workspace](https://mastra.ai/docs/workspace/skills). Attach them to the agent when the skills belong to that specific agent and you want to define them in code with no workspace required. Use a workspace when you want skills discovered from the filesystem and shared across every agent that uses it. This page covers the agent-level approach, defining skills in code and loading them from files, plus resolving them per request.
 
 ## When to use agent-level skills
 

package/.docs/docs/agents/using-tools.md

@@ -326,7 +326,7 @@ For more phases, including `input`, `inputDelta`, `error`, `approval`, `suspend`
 
 ## Run logic around tool calls
 
-Use `hooks` to run custom logic before and after every tool call an agent makes. Hooks apply to all tool sources: assigned tools, memory tools, toolsets, client tools, agent and workflow tools, and [workspace tools](https://mastra.ai/docs/workspace/overview). Common uses include logging, auditing, input validation, and blocking specific calls.
+Use `hooks` to run custom logic before and after every tool call an agent makes. Hooks apply to all tool sources: assigned tools, memory tools, toolsets, client tools, agent and workflow tools, and [workspace tools](https://mastra.ai/reference/workspace/workspace-class). Common uses include logging, auditing, input validation, and blocking specific calls.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'

package/.docs/docs/harness/agent-controller.md

@@ -412,6 +412,6 @@ Subscriptions are isolated by Session. Events from another Session on the same c
 ## Related
 
 - [Agents](https://mastra.ai/docs/agents/overview)
-- [Workspace](https://mastra.ai/docs/workspace/overview)
+- [Workspace](https://mastra.ai/docs/workspace/sandbox)
 - [Observational memory](https://mastra.ai/docs/memory/observational-memory)
 - [Channels](https://mastra.ai/docs/capabilities/channels)

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

@@ -252,7 +252,7 @@ Use an MCP App when a tool result benefits from interaction, such as a form, cal
 
 ### Define an app resource
 
-Return a short `content` summary for the model and place UI data in `structuredContent`. Link the tool to its app by setting `_meta.ui.resourceUri` to the same `ui://` URI used in `appResources`:
+Return a short `content` summary for the model and place UI data in `structuredContent`. Link the tool to its app by setting `mcp._meta.ui.resourceUri` to the same `ui://` URI used in `appResources`:
 
 ```typescript
 import { MCPServer } from '@mastra/mcp'
@@ -266,16 +266,15 @@ export const calculatorTool = createTool({
     num1: z.number(),
     num2: z.number(),
   }),
+  mcp: {
+    _meta: { ui: { resourceUri: 'ui://calculator/main' } },
+  },
   execute: async ({ num1, num2 }) => ({
     content: [{ type: 'text', text: 'The result is displayed in the calculator app.' }],
     structuredContent: { result: num1 + num2 },
   }),
 })
 
-calculatorTool._meta = {
-  ui: { resourceUri: 'ui://calculator/main' },
-}
-
 export const calculatorMcpServer = new MCPServer({
   id: 'calculator-app-server',
   name: 'Calculator App Server',

package/.docs/docs/studio/overview.md

@@ -85,7 +85,7 @@ Run tools on their own to observe behavior and test them before assigning them t
 
 Browse the files in your agent's workspace filesystem using a built-in file browser. Switch between workspace mounts, create directories, and view file contents with syntax highlighting. Writable workspaces allow directory creation and file deletion; read-only workspaces are labeled accordingly. The Skills tab lists all discovered skills with their instructions, references, and metadata. Install community skills from [skills.sh](https://skills.sh) or remove existing ones.
 
-See [workspaces](https://mastra.ai/docs/workspace/overview) for configuration details.
+See [workspaces](https://mastra.ai/docs/workspace/sandbox) for configuration details.
 
 ### Request context
 

package/.docs/docs/workspace/filesystem.md

@@ -2,237 +2,266 @@
 
 # Filesystem
 
-**Added in:** `@mastra/core@1.1.0`
+Filesystems give agents persistent storage for source code, documents, datasets, and generated artifacts.
 
-Filesystem providers give agents the ability to read, write, and manage files. When you configure a filesystem on a workspace, agents receive tools for file operations.
+Mastra supports two mutually exclusive ways to add a filesystem to a workspace:
 
-A filesystem provider handles all file operations for a workspace:
+| Configuration | Agent access | Sandbox access                                 |
+| ------------- | ------------ | ---------------------------------------------- |
+| `mounts`      | File tools   | Files appear as local directories through FUSE |
+| `filesystem`  | File tools   | No access                                      |
 
-- **Read** - Read file contents
-- **Write** - Create and update files
-- **List** - Browse directories with optional glob pattern filtering
-- **Delete** - Remove files and directories
-- **Stat** - Get file metadata
-- **Copy/Move** - Copy or move files between locations
-- **Grep** - Search file contents using regex patterns
+Use `mounts` when a sandbox needs to run commands against the files. The agent can use file tools, while code inside the sandbox can use shell commands and libraries against the same storage.
 
-## Supported providers
+Use `filesystem` when the agent only needs direct file tools or the sandbox backend doesn't support mounts. The agent acts as the driver: it can read a file and pass its contents to another tool, but the file doesn't exist inside the sandbox. A command such as `cat`, `grep`, or `python script.py` can't access it unless your application passes the content as input.
 
-Available providers:
+You can't configure both `filesystem` and `mounts` on the same workspace.
 
-- [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem): Stores files in a directory on disk
-- [`S3Filesystem`](https://mastra.ai/integrations/file-storage/amazon-s3): Stores files in Amazon S3 or S3-compatible storage (R2, MinIO, Tigris)
-- [`GCSFilesystem`](https://mastra.ai/integrations/file-storage/google-cloud-storage): Stores files in Google Cloud Storage
-- [`PlatformFilesystem`](https://mastra.ai/reference/workspace/platform-filesystem): Stores files in a Mastra Platform workspace bucket
-- [`GoogleDriveFilesystem`](https://mastra.ai/integrations/file-storage/google-drive): Stores files inside a Google Drive folder
-- [`AzureBlobFilesystem`](https://mastra.ai/integrations/file-storage/azure-blob): Stores files in Azure Blob Storage
-- [`FilesSDKFilesystem`](https://mastra.ai/integrations/file-storage/vercel-files): Stores files in any [FilesSDK](https://files-sdk.dev) adapter (S3, R2, GCS, Azure Blob, Vercel Blob, local filesystem, and more): useful when you want one provider that can target multiple backends
-- [`AgentFSFilesystem`](https://mastra.ai/integrations/file-storage/agentfs): Stores files in a Turso/SQLite database via AgentFS
-- [`MesaFilesystem`](https://mastra.ai/integrations/file-storage/mesa): Stores files in versioned Mesa repos
-- [`ArchilFilesystem`](https://mastra.ai/integrations/file-storage/archil): Stores files on Archil elastic, serverless disks
+## When to use filesystems
 
-> **Tip:** `LocalFilesystem` is the simplest way to get started as it requires no external services. For cloud storage, use `S3Filesystem`, `GCSFilesystem`, or `AzureBlobFilesystem`. For versioned storage, use `MesaFilesystem`. For database-backed storage without external services, use `AgentFSFilesystem`.
+Mount a filesystem when you want to:
 
-## Basic usage
+- Seed an ephemeral sandbox with source code, datasets, or project files.
+- Persist files after the sandbox stops or is deleted.
+- Let commands and agent file tools work against the same storage.
+- Share a storage location across multiple sandbox runs.
 
-Create a workspace with a filesystem and assign it to an agent. The agent can then read, write, and manage files as part of its tasks:
+Use a workspace-only filesystem when you want to:
 
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
+- Give an agent access to a managed knowledge base without command execution.
+- Read documents uploaded by non-technical teammates to services such as S3 or Google Drive.
+- Use persistent storage with a sandbox backend that doesn't support mounts.
+- Keep the storage provider separate from the sandbox execution environment.
 
-const workspace = new Workspace({
-  filesystem: new LocalFilesystem({
-    basePath: './workspace',
-  }),
-})
+For example, a real-estate agent could read travel-policy documents from an S3 bucket or Google Drive folder and use them while answering questions. The agent can search and read those files without needing a sandbox to execute commands against them.
 
-const agent = new Agent({
-  id: 'file-agent',
-  model: 'openai/gpt-5.6-sol',
-  instructions: 'You are a helpful file management assistant.',
-  workspace,
-})
+A data agent could also download reports from Google Drive with file tools. It can pass their contents to a sandbox for analysis and presentation generation, then upload the finished presentation for the team. This works even when the sandbox backend can't mount Google Drive because the agent transfers the input and output between the filesystem and sandbox.
 
-// The agent now has filesystem tools available
-const response = await agent.generate('List all files in the workspace')
-```
+## Supported filesystems
 
-## Containment
+### `LocalFilesystem`
 
-By default, `LocalFilesystem` runs in **contained mode**, all file operations are restricted to stay within `basePath`. This prevents path traversal attacks and symlink escapes.
+[`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) stores files in a directory on the same machine as your Mastra application. Use it for local development or when the application already has access to the files on disk.
 
-In contained mode:
+`LocalFilesystem` contains file-tool access within its configured `basePath` by default. You can allow specific paths outside that directory or disable containment when the application requires broader host access.
 
-- **Relative paths** (e.g. `src/index.ts`) resolve against `basePath`
-- **Absolute paths** (e.g. `/home/user/.config/file.txt`) are treated as real filesystem paths: if they fall outside `basePath` and any `allowedPaths`, a `PermissionError` is thrown
-- **Tilde paths** (e.g. `~/Documents`) expand to the home directory and follow the same containment rules
+### Other filesystems
 
-If your agent needs to access specific paths outside `basePath`, use `allowedPaths` to grant access without disabling containment entirely. Relative paths are resolved against `basePath`, and absolute paths are used as-is:
+Use another filesystem when files need to persist outside the application host or already live in an external service:
 
-```typescript
-const workspace = new Workspace({
-  filesystem: new LocalFilesystem({
-    basePath: './workspace',
-    allowedPaths: ['~/.claude/skills', '../shared-data'],
-  }),
-})
-```
+- [AgentFS](https://mastra.ai/integrations/file-storage/agentfs)
+- [Amazon S3](https://mastra.ai/integrations/file-storage/amazon-s3)
+- [Archil](https://mastra.ai/integrations/file-storage/archil)
+- [Azure Blob](https://mastra.ai/integrations/file-storage/azure-blob)
+- [Google Cloud Storage](https://mastra.ai/integrations/file-storage/google-cloud-storage)
+- [Google Drive](https://mastra.ai/integrations/file-storage/google-drive)
+- [Mastra Platform](https://mastra.ai/reference/workspace/platform-filesystem)
+- [Mesa](https://mastra.ai/integrations/file-storage/mesa)
+- [Vercel Files](https://mastra.ai/integrations/file-storage/vercel-files)
 
-Allowed paths can be updated at runtime using the `setAllowedPaths()` method:
+Workspace-only file tools work with the full provider list. FUSE mount support depends on both the filesystem and sandbox backend, so check both references before choosing a combination.
 
-```typescript
-// Add a path dynamically
-workspace.filesystem.setAllowedPaths(prev => [...prev, '/home/user/documents'])
-```
+## Mounts
 
-This is the recommended approach for least-privilege access, the agent can only reach the specific directories you allow.
+Use mounts when both the agent and sandbox commands need access to the same files.
 
-If your agent needs unrestricted access to the entire filesystem, disable containment:
+### Quickstart
+
+Mount an S3 filesystem into a sandbox:
 
 ```typescript
+import { Mastra } from '@mastra/core'
+import { Workspace } from '@mastra/core/workspace'
+import { DaytonaSandbox } from '@mastra/daytona'
+import { S3Filesystem } from '@mastra/s3'
+
 const workspace = new Workspace({
-  filesystem: new LocalFilesystem({
-    basePath: './workspace',
-    contained: false,
-  }),
+  mounts: {
+    '/workspace': new S3Filesystem({
+      bucket: process.env.S3_BUCKET!,
+      region: process.env.S3_REGION!,
+    }),
+  },
+  sandbox: new DaytonaSandbox(),
 })
+
+export const mastra = new Mastra({ workspace })
 ```
 
-When `contained` is `false`, absolute paths are treated as real filesystem paths with no restriction.
+Existing objects in the bucket seed the sandbox at `/workspace`. Files created there persist in S3 after the sandbox stops. All agents registered with this `Mastra` instance inherit the workspace.
+
+### Using mounts
+
+The agent receives file tools for mounted storage:
+
+| Tool         | Does                                                       |
+| ------------ | ---------------------------------------------------------- |
+| `read_file`  | Reads text or binary file contents.                        |
+| `write_file` | Creates or replaces a file.                                |
+| `edit_file`  | Applies targeted edits to a text file.                     |
+| `list_files` | Lists files and directories, with optional glob filtering. |
+| `file_stat`  | Returns file metadata.                                     |
+| `mkdir`      | Creates a directory.                                       |
+| `delete`     | Deletes files or directories.                              |
+| `grep`       | Searches file contents with a regular expression.          |
+
+Mounted files are also available to commands inside the sandbox. In the Quickstart, `read_file('/workspace/report.md')` and `cat /workspace/report.md` read the same S3 object.
 
-## Dynamic filesystem
+Use `WORKSPACE_TOOLS.FILESYSTEM` to require approval, disable tools, enforce read-before-write, or change output limits. See the [Workspace filesystem tools reference](https://mastra.ai/reference/workspace/workspace-class) for configuration details.
 
-The `filesystem` option accepts a resolver function instead of a static instance. The resolver receives `requestContext` and returns a filesystem per request, allowing a single workspace to serve different filesystems based on the caller's identity, role, or tenant.
+> **Warning:** File-tool policies only apply to file-tool calls. Restrictions such as `allowedPaths`, approval rules, or read-before-write don't constrain shell commands running inside the sandbox. A command can access any mounted path allowed by the sandbox backend and mount configuration. If the agent must not bypass file-tool policies through the shell, disable its sandbox command tools.
+
+### Multiple mounts
+
+The `mounts` option creates a `CompositeFilesystem` that routes paths to storage providers by mount prefix. Supported sandbox backends expose those providers as local directories through FUSE.
 
 ```typescript
-import { Agent } from '@mastra/core/agent'
-import { Workspace, LocalFilesystem } from '@mastra/core/workspace'
+import { Workspace } from '@mastra/core/workspace'
+import { E2BSandbox } from '@mastra/e2b'
+import { GCSFilesystem } from '@mastra/gcs'
+import { S3Filesystem } from '@mastra/s3'
 
 const workspace = new Workspace({
-  filesystem: ({ requestContext }) => {
-    const role = requestContext.get('agent-role') || 'guest'
-    return new LocalFilesystem({
-      basePath: `/workspaces/${role}`,
-      readOnly: role !== 'admin',
-    })
+  mounts: {
+    '/data': new S3Filesystem({
+      bucket: 'agent-data',
+      region: 'us-east-1',
+    }),
+    '/reports': new GCSFilesystem({
+      bucket: 'agent-reports',
+    }),
   },
-})
-
-const agent = new Agent({
-  id: 'multi-role-agent',
-  model: 'openai/gpt-5.6-sol',
-  workspace,
+  sandbox: new E2BSandbox({ id: 'analysis-sandbox' }),
 })
 ```
 
-Each request resolves its own filesystem for workspace tools and workspace instructions:
+With this configuration:
 
-```typescript
-import { RequestContext } from '@mastra/core/request-context'
+- Existing objects under `/data` and `/reports` seed the sandbox when the mounts become available.
+- Agent file tools route each path to its corresponding storage provider.
+- Commands inside the sandbox access the same paths.
+- New and updated files persist in the underlying buckets.
 
-// Admin request — reads and writes from /workspaces/admin/
-const adminCtx = new RequestContext([['agent-role', 'admin']])
-await agent.generate('Write report.txt with Q4 results', { requestContext: adminCtx })
+All file paths must start with a mount prefix. Listing `/` returns a virtual directory for each mount. Mount paths can't be nested, so a workspace can't mount both `/data` and `/data/archive`.
 
-// Viewer request — reads from /workspaces/viewer/, writes are blocked
-const viewerCtx = new RequestContext([['agent-role', 'viewer']])
-await agent.generate('Read info.txt', { requestContext: viewerCtx })
-```
+Mount support varies by sandbox backend and filesystem provider. Check both references before choosing a combination.
 
-Workspace instructions use the same `requestContext`, so the agent sees the filesystem context for the resolved provider.
+### Read-only mounts
 
-The resolver can also be asynchronous, for example to look up configuration from a database:
+Set `readOnly: true` on a filesystem provider when the sandbox and agent should only read seeded files. Mastra excludes write tools for provider objects known to be read-only, and the mount backend enforces its own write restrictions.
 
 ```typescript
 const workspace = new Workspace({
-  filesystem: async ({ requestContext }) => {
-    const tenantConfig = await db.getTenant(requestContext.get('tenant-id'))
-    return new LocalFilesystem({ basePath: tenantConfig.storagePath })
+  mounts: {
+    '/policies': new S3Filesystem({
+      bucket: 'company-policies',
+      region: 'us-east-1',
+      readOnly: true,
+    }),
   },
+  sandbox: new DaytonaSandbox(),
 })
 ```
 
-> **Note:** `filesystem` and `mounts` are mutually exclusive. You can't use a resolver function together with `mounts` in the same workspace.
+### Per-user or per-thread mounts
+
+Workspace-level `mounts` require a sandbox provider object and can't be combined with a sandbox resolver. For one sandbox and storage prefix per user or thread, create and mount the filesystem inside the sandbox resolver. See [Multi-tenant sandboxes](https://mastra.ai/docs/workspace/sandbox) for a complete example.
+
+## Workspace-only filesystem
 
-## Read-only mode
+Pass a provider to `filesystem` when only the agent needs file access. The agent receives file tools, but a sandbox configured on the same workspace can't see those files.
 
-To prevent agents from modifying files, enable read-only mode:
+### Quickstart
 
 ```typescript
+import { LocalSandbox, Workspace } from '@mastra/core/workspace'
+import { GoogleDriveFilesystem } from '@mastra/google-drive'
+
 const workspace = new Workspace({
-  filesystem: new LocalFilesystem({
-    basePath: './workspace',
-    readOnly: true,
+  filesystem: new GoogleDriveFilesystem({
+    folderId: process.env.GOOGLE_DRIVE_FOLDER_ID!,
+    accessToken: process.env.GOOGLE_DRIVE_ACCESS_TOKEN!,
+  }),
+  sandbox: new LocalSandbox({
+    workingDirectory: './workspace',
   }),
 })
 ```
 
-With a static filesystem, write tools (`write_file`, `edit_file`, `delete`, `mkdir`) are excluded from the agent's toolset entirely. The agent can still read and list files.
+The agent receives the same file tools listed under [Using mounts](#using-mounts), plus sandbox command tools. It can use both in one task. For the prompt "Format `draft.md` with Prettier and save it as `formatted.md`", the agent can:
+
+1. Read `draft.md` from Google Drive with `read_file`.
+2. Pass the returned content to `execute_command`, for example by piping it into Prettier.
+3. Write the command output to `formatted.md` with `write_file`.
 
-When using a [dynamic filesystem](#dynamic-filesystem), write tools are always included because `readOnly` isn't known until the resolver runs. Instead, write operations are blocked at runtime, the tool returns an error if the resolved filesystem is read-only.
+The Google Drive files never appear inside the sandbox. Only the content passed to `execute_command` crosses into the execution environment, and only the returned output is written back.
 
-## Mounts and `CompositeFilesystem`
+### Seed a filesystem
 
-When you use the `mounts` option on a workspace, Mastra creates a `CompositeFilesystem` that routes file operations to the correct provider based on path prefix.
+Files already in the folder seed the workspace. You can also seed any writable provider through its API before the agent uses it:
 
 ```typescript
-import { Workspace } from '@mastra/core/workspace'
-import { S3Filesystem } from '@mastra/s3'
-import { GCSFilesystem } from '@mastra/gcs'
-import { E2BSandbox } from '@mastra/e2b'
+await workspace.filesystem?.writeFile(
+  'travel-policy.md',
+  '# Travel policy\n\nEmployees may book economy flights.',
+)
+```
+
+Filesystem operations initialize the provider on first use. Writes replace existing files by default. Pass `{ overwrite: false }` when existing content must be preserved.
+
+### Containment
+
+`LocalFilesystem` uses contained mode by default. File tools can access `basePath` but can't traverse into unrelated host paths through absolute paths, `..`, or symlinks.
+
+```typescript
+import { LocalFilesystem, Workspace } from '@mastra/core/workspace'
 
 const workspace = new Workspace({
-  mounts: {
-    '/data': new S3Filesystem({
-      bucket: 'my-bucket',
-      region: 'us-east-1',
-      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
-      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
-    }),
-    '/skills': new GCSFilesystem({
-      bucket: 'agent-skills',
-    }),
-  },
-  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
+  filesystem: new LocalFilesystem({
+    basePath: './knowledge-base',
+    allowedPaths: ['../shared-policies'],
+  }),
 })
 ```
 
-With this configuration:
-
-- `read_file('/data/input.csv')` reads from the S3 bucket
-- `write_file('/skills/guide.md', content)` writes to the GCS bucket
-- `list_directory('/')` returns virtual entries for `/data` and `/skills`
-- Commands in the sandbox can access files at `/data` and `/skills` via FUSE mounts
-
-### Path routing
+Containment still matters even though the agent accesses files through tools. It limits what those tools can expose. Prefer `allowedPaths` for specific external directories instead of setting `contained: false`.
 
-All file paths must start with a mount prefix because operations fail when their paths don't match a mount. Listing the root directory (`/`) returns virtual directory entries for each mount point.
+### Read-only mode
 
-Mount paths can't be nested, for example, you can't mount at both `/data` and `/data/sub`.
+Set `readOnly: true` when the agent should use seeded content without changing it:
 
-### `filesystem` vs `mounts`
+```typescript
+const workspace = new Workspace({
+  filesystem: new LocalFilesystem({
+    basePath: './knowledge-base',
+    readOnly: true,
+  }),
+})
+```
 
-`filesystem` and `mounts` are mutually exclusive options on a workspace:
+For a provider object, Mastra removes write, edit, delete, and directory-creation tools. For a resolver-backed filesystem, the tools remain registered because the provider isn't known until execution. Write attempts are rejected at runtime.
 
-- Use **`filesystem`** when you have a single storage provider and don't need to mount it into a sandbox. The agent gets file tools that operate directly against the provider.
-- Use **`mounts`** when you need cloud storage accessible inside a sandbox, or when you want to combine multiple providers. The workspace creates a CompositeFilesystem for file tools and FUSE-mounts the storage into the sandbox.
+### Multi-tenant filesystems
 
-For local development, you typically don't need `mounts`, a `LocalFilesystem` and `LocalSandbox` pointed at the same directory gives you both file tools and command execution on the same files. See [configuration patterns](https://mastra.ai/docs/workspace/overview) for more detail.
+Use a resolver when each request, user, role, or tenant needs different storage:
 
-## Agent tools
+```typescript
+const workspace = new Workspace({
+  filesystem: ({ requestContext }) => {
+    const tenantId = requestContext.get('tenant-id') as string
+    return new S3Filesystem({
+      bucket: process.env.S3_BUCKET!,
+      region: process.env.S3_REGION!,
+      prefix: `tenants/${tenantId}`,
+    })
+  },
+})
+```
 
-When you configure a filesystem on a workspace, agents receive tools for reading, writing, listing, and deleting files. See [workspace class reference](https://mastra.ai/reference/workspace/workspace-class) for details.
+Each tenant's prefix seeds its own workspace view. Workspace tools resolve the filesystem from the request context automatically.
 
 ## Related
 
-- [LocalFilesystem reference](https://mastra.ai/reference/workspace/local-filesystem)
-- [S3Filesystem reference](https://mastra.ai/integrations/file-storage/amazon-s3)
-- [GCSFilesystem reference](https://mastra.ai/integrations/file-storage/google-cloud-storage)
-- [GoogleDriveFilesystem reference](https://mastra.ai/integrations/file-storage/google-drive)
-- [AzureBlobFilesystem reference](https://mastra.ai/integrations/file-storage/azure-blob)
-- [FilesSDKFilesystem reference](https://mastra.ai/integrations/file-storage/vercel-files)
-- [AgentFSFilesystem reference](https://mastra.ai/integrations/file-storage/agentfs)
-- [MesaFilesystem reference](https://mastra.ai/integrations/file-storage/mesa)
-- [Workspace overview](https://mastra.ai/docs/workspace/overview)
-- [Sandbox](https://mastra.ai/docs/workspace/sandbox)
+- [Sandbox](https://mastra.ai/docs/workspace/sandbox)
+- [`WorkspaceFilesystem` reference](https://mastra.ai/reference/workspace/filesystem)
+- [`Workspace` reference](https://mastra.ai/reference/workspace/workspace-class)

package/.docs/docs/workspace/lsp.md

@@ -2,8 +2,6 @@
 
 # LSP inspection
 
-**Added in:** `@mastra/core@1.1.0`
-
 LSP inspection gives workspace-backed agents semantic code intelligence. When you enable LSP on a workspace, agents can inspect symbols in supported files to retrieve hover information and jump to definitions. They can also find implementations.
 
 ## When to use LSP inspection
@@ -16,7 +14,7 @@ Use LSP inspection when your agent needs semantic code understanding instead of
 - Combine semantic inspection with `view` and `search_content` for faster navigation
 - Add LSP support for additional languages by [registering custom language servers](#custom-language-servers)
 
-## Basic usage
+## Quickstart
 
 Enable LSP on a workspace by setting `lsp: true`:
 
@@ -57,7 +55,7 @@ The tool returns up to three result groups:
 
 ## Tool name remapping
 
-Rename the tool if your agent expects a shorter name:
+Use `WORKSPACE_TOOLS.LSP.LSP_INSPECT` to configure the inspection tool. Set `enabled: false` to remove it from the agent's toolset, or set `name` if the agent expects a different name:
 
 ```typescript
 import { Workspace, LocalFilesystem, WORKSPACE_TOOLS } from '@mastra/core/workspace'
@@ -75,6 +73,8 @@ const workspace = new Workspace({
 
 This changes the exposed tool name only. The configuration key stays `WORKSPACE_TOOLS.LSP.LSP_INSPECT`.
 
+See [`WorkspaceToolsConfig`](https://mastra.ai/reference/workspace/workspace-class) for approval settings, dynamic policies, output limits, and hooks shared by workspace tools.
+
 ## LSP configuration
 
 Set `lsp` to `true` for default behavior, or provide an object to customize server startup and diagnostics:
@@ -210,7 +210,6 @@ const workspace = new Workspace({
 
 ## Related
 
-- [Workspace overview](https://mastra.ai/docs/workspace/overview)
 - [Filesystem](https://mastra.ai/docs/workspace/filesystem)
 - [Sandbox](https://mastra.ai/docs/workspace/sandbox)
 - [Search and indexing](https://mastra.ai/docs/workspace/search)