@mastra/mcp-docs-server 1.2.6 → 1.2.7-alpha.10

package/.docs/reference/auth/google.md

@@ -75,7 +75,7 @@ The following environment variables are automatically used when constructor opti
 1. **Session cookie**: When SSO is enabled, reads the encrypted session cookie and decrypts it. If the session is valid and not expired, the user is authenticated.
 2. **Google ID token fallback**: If no valid session cookie is present, verifies the `Authorization` header token against Google's JWKS endpoint.
 
-After authentication, `authorizeUser` checks that the user has a valid Google user ID, the token-derived expiration has not passed, and the user's verified `hd` claim matches `allowedDomains` when domains are configured.
+After authentication, `authorizeUser` checks that the user has a valid Google user ID, the token-derived expiration hasn't passed, and the user's verified `hd` claim matches `allowedDomains` when domains are configured.
 
 ### Authentication methods
 
@@ -101,7 +101,7 @@ Returns: `Promise<GoogleUser | null>`
 
 #### `authorizeUser(user)`
 
-Returns `true` when the user has an ID, has not expired, and matches `allowedDomains` when domains are configured.
+Returns `true` when the user has an ID, hasn't expired, and matches `allowedDomains` when domains are configured.
 
 ```typescript
 const allowed = auth.authorizeUser(user)
@@ -111,7 +111,7 @@ Returns: `boolean`
 
 #### `getUser(userId)`
 
-Returns `null`. Google ID tokens are verified directly, so this provider does not perform user lookup by ID.
+Returns `null`. Google ID tokens are verified directly, so this provider doesn't perform user lookup by ID.
 
 ```typescript
 const user = await auth.getUser(userId)
@@ -348,9 +348,9 @@ Returns: `{ size: number; maxSize: number }`
 
 `MastraRBACGoogle` uses `GET https://admin.googleapis.com/admin/directory/v1/groups?userKey=...` and handles pagination. Provide a service account with domain-wide delegation for production Google Workspace deployments, or pass `accessToken` / `getAccessToken` if your application already manages Google API tokens.
 
-If `user.groups` is already an array, `MastraRBACGoogle` uses that value and does not call the Directory API. An empty `groups` array means the user has no Google group roles and resolves to `_default` permissions when `_default` is configured.
+If `user.groups` is already an array, `MastraRBACGoogle` uses that value and doesn't call the Directory API. An empty `groups` array means the user has no Google group roles and resolves to `_default` permissions when `_default` is configured.
 
-`MastraRBACGoogle` does not automatically read service-account environment variables. Pass service-account credentials through the `serviceAccount` option, or pass `accessToken` / `getAccessToken`.
+`MastraRBACGoogle` doesn't automatically read service-account environment variables. Pass service-account credentials through the `serviceAccount` option, or pass `accessToken` / `getAccessToken`.
 
 ## Related
 

package/.docs/reference/channels/channel-provider.md

@@ -64,4 +64,4 @@ const all = mastra.getChannelProviders()
 ## Related
 
 - [SlackProvider](https://mastra.ai/reference/channels/slack-provider)
-- [Channels](https://mastra.ai/docs/agents/channels)
+- [Channels](https://mastra.ai/docs/capabilities/channels/overview)

package/.docs/reference/channels/slack-provider.md

@@ -2,7 +2,7 @@
 
 # SlackProvider
 
-`SlackProvider` is the managed path for connecting agents to Slack. Register it on `Mastra.channels` and it provisions Slack apps via the Manifest API, runs the OAuth install flow, rotates configuration tokens, and routes Slack events to your agents. Use it when you want Mastra to own app creation and installation. For the lower-level path where you create the Slack app and configure scopes and webhooks yourself, use [`createSlackAdapter`](https://mastra.ai/docs/agents/channels) on the agent's `channels.adapters` instead.
+`SlackProvider` is the managed path for connecting agents to Slack. Register it on `Mastra.channels` and it provisions Slack apps via the Manifest API, runs the OAuth install flow, rotates configuration tokens, and routes Slack events to your agents. Use it when you want Mastra to own app creation and installation. For the lower-level path where you create the Slack app and configure scopes and webhooks yourself, use [`createSlackAdapter`](https://mastra.ai/docs/capabilities/channels/slack) on the agent's `channels.adapters` instead.
 
 ## Usage example
 
@@ -171,7 +171,7 @@ slack.setBaseUrl('https://abc123.trycloudflare.com')
 
 #### `initialize()`
 
-Recreates a `SlackAdapter` for each active installation in storage and injects `AgentChannels` into the corresponding agent so it receives Slack events on startup. Does not auto-provision new apps; use `connect()` to create one. Mastra calls this automatically, so you rarely call it directly.
+Recreates a `SlackAdapter` for each active installation in storage and injects `AgentChannels` into the corresponding agent so it receives Slack events on startup. Doesn't auto-provision new apps; use `connect()` to create one. Mastra calls this automatically, so you rarely call it directly.
 
 ```typescript
 await slack.initialize()
@@ -224,5 +224,5 @@ const result = await slack.connect('support-agent')
 ## Related
 
 - [ChannelProvider](https://mastra.ai/reference/channels/channel-provider): the interface `SlackProvider` implements
-- [Channels](https://mastra.ai/docs/agents/channels): concepts, platform setup, and the `createSlackAdapter` path
+- [Channels](https://mastra.ai/docs/capabilities/channels/overview): concepts, platform setup, and the `createSlackAdapter` path
 - [Channels reference](https://mastra.ai/reference/agents/channels): the `channels` config on the `Agent` constructor

package/.docs/reference/cli/mastra.md

@@ -215,7 +215,7 @@ If the project doesn't exist yet, the CLI creates it from the `package.json` `na
 mastra deploy --env staging --yes
 ```
 
-When `--env <name>` is set and `--env-file` is not, the CLI auto-selects `.env.<name>` from the project directory if present (for example `.env.staging`). The `<name>` value is validated against a strict allowlist before being interpolated into a file path.
+When `--env <name>` is set and `--env-file` isn't, the CLI auto-selects `.env.<name>` from the project directory if present (for example `.env.staging`). The `<name>` value is validated against a strict allowlist before being interpolated into a file path.
 
 ### Arguments
 
@@ -227,7 +227,7 @@ Project directory. Defaults to the current directory.
 
 #### `--env`
 
-Target environment name. Defaults to `production`. Auto-selects `.env.<name>` from the project directory when `--env-file` is not set. If the environment doesn't exist, the CLI creates it after confirmation.
+Target environment name. Defaults to `production`. Auto-selects `.env.<name>` from the project directory when `--env-file` isn't set. If the environment doesn't exist, the CLI creates it after confirmation.
 
 #### `--org`
 
@@ -282,32 +282,30 @@ mastra deploy --env staging --yes
 
 ## `mastra env`
 
-Manages environments on Mastra platform. Environments are named deploy targets (for example `production`, `staging`, `preview-42`) that belong to a project. Every subcommand takes a `<project>` argument (name, slug, or ID) and resolves the current organization from stored credentials.
+Manages environments on Mastra platform. Environments are named deploy targets (for example `production`, `staging`, `preview-42`) that belong to a project. The current organization is resolved from stored credentials.
+
+Every subcommand resolves its project from, in order: the `MASTRA_PROJECT_ID` environment variable, the `--project <name|slug|id>` flag, or the `.mastra-project.json` file written by [`mastra deploy`](#mastra-deploy) in the current directory. Run from your project directory and you never need to name the project.
 
 ### `mastra env list`
 
-Lists environments for a project.
+Lists environments for a project. Each environment shows its latest deploy (with an `(active)` marker when it's serving traffic) and the env var names injected by managed resources such as attached databases.
 
 ```bash
-mastra env list <project>
+mastra env list
 ```
 
 #### `--json`
 
-Emit machine-readable JSON. Only non-sensitive metadata (id, name, slug, type, region, branch, and URLs) is included so the output is safe to log in CI.
+Emit machine-readable JSON. Only non-sensitive metadata (id, name, slug, type, region, branch, URLs, managed env var names, and latest deploy status) is included so the output is safe to log in CI.
 
 ### `mastra env create`
 
 Creates a new environment for a project.
 
 ```bash
-mastra env create <project> --name staging --type staging --region eu
+mastra env create staging --type staging --region eu
 ```
 
-#### `-n, --name`
-
-Environment name (required).
-
 #### `-t, --type`
 
 Environment type. One of `production`, `staging`, or `preview`. Defaults to `staging`.
@@ -325,7 +323,7 @@ Emit machine-readable JSON. Sensitive fields are omitted, as with [`mastra env l
 Deletes an environment.
 
 ```bash
-mastra env delete <project> <env>
+mastra env delete <env>
 ```
 
 `<env>` can be an environment name, slug, or ID. The CLI prompts for confirmation unless `--yes` is passed.
@@ -334,6 +332,112 @@ mastra env delete <project> <env>
 
 Skip the confirmation prompt.
 
+### `mastra env restart`
+
+Restarts an environment's running service so saved env vars (including managed vars from attached databases) take effect immediately, without a new deploy.
+
+```bash
+mastra env restart <env>
+```
+
+`<env>` can be an environment name, slug, or ID. Fails with a conflict error if the environment has never been deployed.
+
+### `mastra env db`
+
+Manages databases attached to a project on Mastra platform. Databases are provisioned from a managed provider (for example Turso or Neon) and inject their connection env vars into deploys automatically.
+
+A database is either **environment-scoped** (its env vars only go to one environment) or **shared** (project-scoped: its env vars go to all environments). Pass the environment argument to work with environment-scoped databases; omit it for shared databases.
+
+Creating and detaching databases requires the `admin` role in the organization.
+
+### `mastra env db list`
+
+Lists databases attached to a project, including provider, provisioning status, scope (which environment each database feeds), and the env var names each database injects. Pass an environment to only show databases feeding that environment (environment-scoped plus shared).
+
+```bash
+mastra env db list
+mastra env db list <env>
+```
+
+#### `--json`
+
+Emit machine-readable JSON.
+
+### `mastra env db create`
+
+Provisions a managed database, attaches it, and polls until it's ready. Provisioning errors are printed with the provider's error detail.
+
+With an environment argument, the database is scoped to that environment: only it receives the database's connection env vars, and the provider region is derived from the environment's region. Without one, the database is shared by all environments.
+
+```bash
+mastra env db create <env> --kind turso
+mastra env db create --kind neon --name my-app-db --region aws-us-east-1
+```
+
+#### `--kind`
+
+Database provider (required). One of `turso` or `neon`.
+
+#### `--name`
+
+Database name. Defaults to a name derived from the project slug (for example `my-app-db`).
+
+#### `--region`
+
+Provider region ID for shared databases. Ignored for environment-scoped databases.
+
+#### `--no-wait`
+
+Return immediately after the attach is queued instead of polling until the database is ready. Check progress later with `mastra env db show`.
+
+#### `--json`
+
+Emit machine-readable JSON.
+
+### `mastra env db show`
+
+Shows database details and, once the database is ready, its connection env vars. Secret values are masked by default.
+
+```bash
+mastra env db show <database>
+```
+
+`<database>` can be a database ID or name.
+
+#### `--show-secrets`
+
+Print secret connection values instead of masking them.
+
+#### `--json`
+
+Emit machine-readable JSON. Secret values are masked unless `--show-secrets` is passed.
+
+### `mastra env db detach`
+
+Detaches a database from the project. The CLI prompts for confirmation unless `--yes` is passed. After detaching, deploys no longer receive the database's env vars.
+
+```bash
+mastra env db detach <database>
+```
+
+#### `-y, --yes`
+
+Skip the confirmation prompt.
+
+### `mastra env deploys`
+
+Lists deploys for a project, newest first. Deploys that are serving traffic are marked `(active)`.
+
+```bash
+mastra env deploys [environment]
+```
+
+Omit `[environment]` to show deploys across all environments; pass an environment name, slug, or ID to filter to one.
+
+#### `--json`
+
+Emit machine-readable JSON.
+
 ## `mastra studio deploy`
 
 > **Info:** `mastra studio deploy` continues to work but is superseded by [`mastra deploy`](#mastra-deploy), which supports named environments (`--env staging`, `--env production`) on a single project. New setups should use `mastra deploy`.
@@ -736,6 +840,7 @@ Runs database migrations to update your storage schema. This command is useful w
 The command bundles your project, connects to your configured storage backend, and executes any pending migrations. Currently supports:
 
 - **Duplicate spans migration**: Removes duplicate `(traceId, spanId)` entries and adds a unique constraint to ensure data integrity.
+- **ClickHouse legacy-to-vNext span migration**: Copies historical spans from the legacy `mastra_ai_spans` table to the vNext `mastra_span_events` schema. Runs in batches to stay within memory limits. See the [ClickHouse storage reference](https://mastra.ai/reference/storage/clickhouse) for details.
 
 ```bash
 mastra migrate
@@ -1379,6 +1484,8 @@ By default, Mastra collects anonymous information about your project like your O
 
 When a server started with `mastra dev` or `mastra start` has observability metrics enabled, Mastra also sends anonymous, aggregated model usage at startup: input and output token counts per provider and model, plus the command (`dev` or `start`) and `NODE_ENV`. No prompts, responses, or other message content is ever sent. You can read the [source code](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/telemetry/usage-telemetry.ts) to check what's collected.
 
+At server startup, Mastra also sends an anonymous project-surface snapshot: counts of registered agents, agent controllers, workflows, tools, processors, vector stores, scorers, workspaces, MCP servers, gateways, and channels, plus booleans for memory, voice, editor, and observability usage and the coarse storage backend category. It doesn't send names or identifiers. You can read the [source code](https://github.com/mastra-ai/mastra/blob/main/packages/core/src/telemetry/feature-telemetry.ts) to check what's collected.
+
 You can opt out of all CLI and usage analytics by setting an environment variable:
 
 ```bash

package/.docs/reference/code-sdk/mount-agent-controller.md

@@ -0,0 +1,76 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# mountAgentControllerOnMastra()
+
+> **Beta:** The `@mastra/code-sdk` package is experimental and subject to breaking changes in minor versions.
+
+The `mountAgentControllerOnMastra()` function builds the Mastra Code agent controller — the coding agent behind the [`mastracode`](https://www.npmjs.com/package/mastracode) CLI, with its modes, tools, memory, and thread management — and registers it on a server-owned [Mastra](https://mastra.ai/reference/core/mastra-class) instance. Use it to serve the Mastra Code agent to your own UI (web app, editor, bot): each client creates or resumes its own isolated session through the returned [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class).
+
+To construct the `Mastra` instance yourself (for example in a deployable entry file), use `prepareAgentControllerMount()` from the same package, which returns the constructor args plus a `finalize()` callback.
+
+## Usage example
+
+```typescript
+import { mountAgentControllerOnMastra } from '@mastra/code-sdk'
+
+const { mastra, controller } = await mountAgentControllerOnMastra({
+  cwd: process.cwd(),
+})
+
+// Each client drives its own session
+const session = await controller.createSession({ resourceId: 'user-123' })
+```
+
+Pass an existing `mastra` to mount the controller onto a Mastra instance that already hosts other primitives:
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { mountAgentControllerOnMastra } from '@mastra/code-sdk'
+
+const mastra = new Mastra({
+  /* ... */
+})
+
+const { controller } = await mountAgentControllerOnMastra({ mastra })
+```
+
+## Parameters
+
+**cwd** (`string`): Working directory for project detection. (Default: `process.cwd()`)
+
+**mastra** (`Mastra`): Existing Mastra instance to mount onto. When omitted, a Mastra is created that owns the controller storage.
+
+**controllerId** (`string`): Id under which the controller is registered on the Mastra instance.
+
+**modes** (`AgentControllerMode[]`): Override agent modes (model ids, colors, which modes exist). (Default: `build/plan/fast`)
+
+**subagents** (`AgentControllerSubagent[]`): Override or extend subagent definitions. (Default: `explore/plan/execute`)
+
+**extraTools** (`Record<string, ToolAction> | (ctx) => Record<string, ToolAction>`): Extra tools merged into the dynamic tool set.
+
+**disabledTools** (`string[]`): Tools removed from the dynamic tool set before exposure to the model.
+
+**storage** (`StorageConfig`): Custom storage config instead of the auto-detected default.
+
+**workspace** (`AgentControllerConfig["workspace"]`): Override the workspace. (Default: `local filesystem + local sandbox based on the detected project`)
+
+**configDir** (`string`): Override the config directory name used for all project-level and global config paths (MCP, hooks, commands, database, skills, agent instructions). (Default: `'.mastracode'`)
+
+**mcpServers** (`Record<string, McpServerConfig>`): Programmatic MCP server configurations, merged with (and overriding) file-based configs.
+
+**buildApiRoutes** (`(deps: { controller, authStorage }) => ApiRoute[]`): Additional API routes registered on the constructed Mastra. Ignored when mastra is provided.
+
+**buildServerConfig** (`(deps: { controller, authStorage }) => ServerConfig`): Additional server config (middleware, CORS) folded onto the constructed Mastra. Ignored when mastra is provided.
+
+## Returns
+
+**mastra** (`Mastra`): The Mastra instance the controller is mounted on (created or passed in).
+
+**controller** (`AgentController`): The initialized Mastra Code agent controller. Create sessions with controller.createSession().
+
+**authStorage** (`AuthStorage`): Credential storage used by the built-in model gateway.
+
+## Related
+
+- [AgentController class](https://mastra.ai/reference/agent-controller/agent-controller-class)
+- [Session class](https://mastra.ai/reference/agent-controller/session)

package/.docs/reference/coding-agent/create-coding-agent.md

@@ -48,7 +48,7 @@ const agent = createCodingAgent({
 
 ## Defaults
 
-The factory only fills a default when you do not provide the corresponding field. Caller-provided values always win.
+The factory only fills a default when you don't provide the corresponding field. Caller-provided values always win.
 
 | Field             | Default when omitted                                                                                                                           |
 | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |

package/.docs/reference/configuration.md

@@ -366,7 +366,7 @@ export const mastra = new Mastra({
 
 Storage provider for persisting application data. Used by memory, workflows, traces, and other components that require persistence. Mastra supports multiple database backends including PostgreSQL, MongoDB, libSQL, and more.
 
-Visit the [Storage documentation](https://mastra.ai/docs/memory/storage) to learn more.
+Visit the [Storage documentation](https://mastra.ai/docs/storage/overview) to learn more.
 
 ```typescript
 import { Mastra } from '@mastra/core'

package/.docs/reference/evals/checks.md

@@ -4,7 +4,7 @@
 
 Quick Checks are zero-LLM, composable micro-scorers for common assertions. They plug into the existing `scorers: [...]` array anywhere scorers are used — in `runEvals`, live scoring, experiments, and Studio.
 
-Internally they are standard `createScorer()` instances, so they have the same observability, storage, and pipeline integration as any other scorer.
+Internally they're standard `createScorer()` instances, so they have the same observability, storage, and pipeline integration as any other scorer.
 
 ## Usage example
 
@@ -46,7 +46,7 @@ Returns: `1` if found, `0` otherwise.
 
 ### `checks.excludes(unwanted, options?)`
 
-Scores 1 if the agent's output text does NOT contain the substring, 0 otherwise.
+Scores 1 if the agent's output text doesn't contain the substring, 0 otherwise.
 
 ```typescript
 checks.excludes('error')
@@ -125,7 +125,7 @@ Returns: `1` if called at least `times` times, `0` otherwise.
 
 ### `checks.didNotCall(toolName)`
 
-Scores 1 if the agent did NOT call the specified tool.
+Scores 1 if the agent didn't call the specified tool.
 
 ```typescript
 checks.didNotCall('delete_user')
@@ -133,7 +133,7 @@ checks.didNotCall('delete_user')
 
 **toolName** (`string`): Name of the tool that must not appear.
 
-Returns: `1` if the tool was not called, `0` otherwise.
+Returns: `1` if the tool wasn't called, `0` otherwise.
 
 ### `checks.toolOrder(expectedOrder)`
 

package/.docs/reference/evals/create-scorer.md

@@ -53,6 +53,14 @@ const scorer = createScorer({
 
 **judge.jsonPromptInjection** (`boolean`): When true, inject the JSON schema into the prompt instead of using the provider's native response\_format API. Set this for models that don't support native structured output (e.g. some Groq Llama models) to avoid a wasted 400 call.
 
+**judge.inputProcessors** (`Processor[]`): Input processors applied to the internal judge agent before its messages reach the model (e.g. redaction, validation).
+
+**judge.outputProcessors** (`Processor[]`): Output processors applied to the internal judge agent's output before it is returned (e.g. moderation, transformation).
+
+**judge.errorProcessors** (`Processor[]`): Error processors for the internal judge agent. These implement processAPIError and can inspect LLM API rejections and signal a retry, e.g. StreamErrorRetryProcessor. Requires maxProcessorRetries to be set for retry-based processors to take effect.
+
+**judge.maxProcessorRetries** (`number`): Maximum number of times processors can trigger a retry per judge generation. Required for retry-based error processors (e.g. StreamErrorRetryProcessor) to take effect.
+
 **type** (`string`): Type specification for input/output. Use 'agent' for automatic agent types. For custom types, use the generic approach instead.
 
 **prepareRun** (`(run: ScorerRun) => ScorerRun | Promise<ScorerRun>`): Transform the scorer run data before the pipeline executes. Use this to filter messages, limit context size, or drop fields the scorer doesn't need. The \`filterRun()\` utility creates this function from declarative options. Can be async.

package/.docs/reference/file-based-agents/config.md

@@ -0,0 +1,97 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# config.ts
+
+An agent's `config.ts` sets its model and runtime options. Use it for options that belong to the [`Agent`](https://mastra.ai/reference/agents/agent) itself, while sibling files provide instructions, tools, skills, et cetera.
+
+## What belongs in `config.ts`
+
+`config.ts` is the required entry point for a file-based agent's model and runtime options. Put agent-level settings here when they don't need their own file, such as the model, description, default execution options, retry behavior, scorers, and display identity.
+
+Keep adjacent concerns in sibling files when you want file-based routing to merge them into the agent. For example, use `instructions.md` for the always-on prompt and `tools/` for model-callable actions.
+
+## Quickstart
+
+The following `config.ts` plus an `instructions.md` file creates a working file-based agent:
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  model: 'openai/gpt-5.5',
+})
+```
+
+```markdown
+You are a helpful weather assistant. Answer questions about current conditions and forecasts.
+```
+
+Mastra uses the `weather` directory name as the default agent `id` and `name`. The sibling `instructions.md` supplies the required instructions.
+
+## Set the model
+
+The `model` field is the only required field in `agentConfig()`. The build fails when an agent directory doesn't provide a model. Other capabilities either come from sibling files or have defaults.
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  model: 'openai/gpt-5.5',
+})
+```
+
+## Identity from the directory
+
+A file-based agent's `id` and `name` default to the directory name. For `src/mastra/agents/weather/`, Mastra registers the agent as `weather` unless you override those fields.
+
+Override `id` or `name` when the stable routing key and the display name should differ.
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  id: 'weather-assistant',
+  name: 'Weather Assistant',
+  model: 'openai/gpt-5.5',
+})
+```
+
+## Set runtime options
+
+`agentConfig()` accepts [`Agent` constructor options](https://mastra.ai/reference/agents/agent), except that `id`, `name`, and sibling-file fields can be supplied by the file-based convention. Use the Agent reference for the full option list.
+
+Please note:
+
+- File-based subagents require a non-empty `description` because the parent model uses it for delegation routing.
+- `defaultOptions`, `maxRetries`, `scorers`, and other Agent options can live in `config.ts` when they don't need their own file.
+
+## Where adjacent settings live
+
+Keep `config.ts` focused on runtime options. Use sibling files for concerns that benefit from their own location.
+
+| Setting      | File or folder                                                                  | Why it lives there                                                   |
+| ------------ | ------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| Instructions | [`instructions.md`](https://mastra.ai/reference/file-based-agents/instructions) | Keeps the always-on prompt readable as markdown                      |
+| Tools        | [`tools/`](https://mastra.ai/reference/file-based-agents/tools)                 | Gives each callable action its own typed module                      |
+| Skills       | [`skills/`](https://mastra.ai/reference/file-based-agents/skills)               | Keeps load-on-demand procedures separate from always-on instructions |
+| Memory       | [`memory.ts`](https://mastra.ai/reference/file-based-agents/memory)             | Configures persistent memory without crowding runtime options        |
+| Workspace    | [`workspace.ts`](https://mastra.ai/reference/file-based-agents/workspace)       | Configures files and sandbox behavior separately from model settings |
+| Processors   | [`processors/`](https://mastra.ai/reference/file-based-agents/processors)       | Separates input and output processing pipelines                      |
+| Subagents    | [`subagents/`](https://mastra.ai/reference/file-based-agents/subagents)         | Gives each specialist child agent its own directory                  |
+
+## Precedence
+
+`config.ts` merges with the agent's other files according to these rules:
+
+| Domain       | Source A                      | Source B                                                                        | Winner                                                  |
+| ------------ | ----------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| Instructions | Dynamic `config.instructions` | [`instructions.md`](https://mastra.ai/reference/file-based-agents/instructions) | Dynamic `config.instructions`                           |
+| Instructions | Static `config.instructions`  | [`instructions.md`](https://mastra.ai/reference/file-based-agents/instructions) | `instructions.md`                                       |
+| Tools        | `config.tools`                | [`tools/`](https://mastra.ai/reference/file-based-agents/tools)                 | Both merge; `config.tools` wins on key collisions       |
+| Tools        | Function `config.tools`       | [`tools/`](https://mastra.ai/reference/file-based-agents/tools)                 | Function `config.tools`; discovered tools are ignored   |
+| Skills       | `config.skills`               | [`skills/`](https://mastra.ai/reference/file-based-agents/skills)               | Both merge; `config.skills` wins on name collisions     |
+| Skills       | Function `config.skills`      | [`skills/`](https://mastra.ai/reference/file-based-agents/skills)               | Function `config.skills`; discovered skills are ignored |
+| Memory       | `config.memory`               | [`memory.ts`](https://mastra.ai/reference/file-based-agents/memory)             | `config.memory`                                         |
+| Workspace    | `config.workspace`            | [`workspace.ts`](https://mastra.ai/reference/file-based-agents/workspace)       | `config.workspace`                                      |
+
+Missing both `instructions.md` and `config.instructions` fails the build. Missing both `config.memory` and `memory.ts` leaves the agent without memory.

package/.docs/reference/file-based-agents/instructions.md

@@ -0,0 +1,54 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Instructions
+
+An agent's `instructions.md` holds its always-on system prompt: the model reads it on every turn. Use it to define the agent's identity, tone, role, and standing rules.
+
+Instructions are always in context, so keep them for stable behavior that applies to every request. Move anything conditional, large, or action-oriented out of `instructions.md` and into [`tools/`](https://mastra.ai/reference/file-based-agents/tools) or [`skills/`](https://mastra.ai/reference/file-based-agents/skills), which the model uses only when relevant.
+
+## Quickstart
+
+Add an `instructions.md` at the agent root. Whatever you write becomes the prompt, so the shortest version is a single sentence.
+
+```markdown
+You are a helpful weather assistant. Answer questions about current conditions and forecasts.
+```
+
+## What goes in instructions
+
+Effective instructions cover the parts of an agent's behavior that don't change between requests:
+
+- Role and identity
+- Tone and style
+- Standing rules
+- Output format
+
+Move conditional, large, or action-oriented guidance into [`tools/`](https://mastra.ai/reference/file-based-agents/tools) or [`skills/`](https://mastra.ai/reference/file-based-agents/skills), which the model uses only when relevant.
+
+## Dynamic instructions
+
+When the prompt needs to change per request, for example based on the current user or runtime context, set a dynamic `instructions` function in [`config.ts`](https://mastra.ai/reference/file-based-agents/config) instead of using `instructions.md`. A function `instructions` wins over `instructions.md`, so the static file is ignored when both are present.
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  model: 'openai/gpt-5.5',
+  instructions: ({ runtimeContext }) => {
+    const tier = runtimeContext.get('tier') ?? 'standard'
+    return `You are a support agent. Treat this as a ${tier}-tier customer.`
+  },
+})
+```
+
+## Build-time behavior
+
+Mastra reads `instructions.md` and inlines its contents into the generated code when the bundler builds your project. The deployed agent doesn't read the file at runtime, so changes to `instructions.md` take effect only after the next build.
+
+## Precedence with config
+
+Instructions can come from `instructions.md` or from the `instructions` field in [`config.ts`](https://mastra.ai/reference/file-based-agents/config):
+
+- A dynamic (function) `instructions` in `config.ts` wins over `instructions.md`.
+- Otherwise `instructions.md` wins over a static `instructions` string.
+- If neither is present, the build fails and names the agent directory.

package/.docs/reference/file-based-agents/memory.md

@@ -0,0 +1,58 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Memory
+
+A file-based agent gets [memory](https://mastra.ai/docs/memory/overview) from a `memory.ts` file that default-exports a [`Memory`](https://mastra.ai/reference/memory/memory-class) instance. Use this page for the file-based convention; use the memory docs for message history, semantic recall, storage, and processors.
+
+Without `memory.ts` or `config.memory`, the agent has no memory by default. Each `generate()` or `stream()` call starts without remembered conversation state unless you pass the prior context yourself.
+
+## Quickstart
+
+Create `memory.ts` next to the agent's `config.ts`:
+
+```typescript
+import { Memory } from '@mastra/memory'
+
+export default new Memory()
+```
+
+The exported instance becomes the agent's `memory`. If your app configures a storage provider on the main Mastra instance, memory data is stored there. See [storage](https://mastra.ai/docs/storage/overview) for more information.
+
+Use the same `resource` and `thread` values when calling the agent to continue a conversation:
+
+```typescript
+const response = await weatherAgent.generate('Remember that I prefer Celsius.', {
+  memory: {
+    resource: 'user-123',
+    thread: 'weather-chat',
+  },
+})
+```
+
+## Configure memory
+
+Pass options to `new Memory()` when the default behavior isn't enough.
+
+```typescript
+import { Memory } from '@mastra/memory'
+
+export default new Memory({
+  options: {
+    lastMessages: 20,
+    workingMemory: {
+      enabled: true,
+      scope: 'resource',
+    },
+  },
+})
+```
+
+Visit the [`Memory` reference](https://mastra.ai/reference/memory/memory-class) for constructor options. Use these pages for related memory features:
+
+- [Storage](https://mastra.ai/docs/storage/overview): configure persistence for memory data.
+- [Semantic recall](https://mastra.ai/docs/memory/semantic-recall): retrieve relevant past messages by semantic meaning.
+- [Memory processors](https://mastra.ai/docs/memory/memory-processors): filter, trim, or transform messages before memory adds them to model context.
+
+## Precedence with config
+
+`config.memory` wins over `memory.ts`. If neither is present, the assembled file-based agent has no memory. See [`config.ts` precedence](https://mastra.ai/reference/file-based-agents/config) for the full merge table.