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

package/.docs/docs/capabilities/channels/whatsapp.md

@@ -0,0 +1,99 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# WhatsApp
+
+WhatsApp channels let a Mastra agent receive customer messages through WhatsApp Business Cloud. Mastra handles the agent wiring and webhook route; the Chat SDK WhatsApp adapter docs cover Meta app setup, credentials, and webhook configuration.
+
+## Install the adapter
+
+Install the WhatsApp adapter from the Chat SDK:
+
+**npm**:
+
+```bash
+npm install @chat-adapter/whatsapp
+```
+
+**pnpm**:
+
+```bash
+pnpm add @chat-adapter/whatsapp
+```
+
+**Yarn**:
+
+```bash
+yarn add @chat-adapter/whatsapp
+```
+
+**Bun**:
+
+```bash
+bun add @chat-adapter/whatsapp
+```
+
+## Agent configuration
+
+Add `createWhatsAppAdapter()` to the agent's `channels.adapters` object:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createWhatsAppAdapter } from '@chat-adapter/whatsapp'
+
+export const whatsappAgent = new Agent({
+  id: 'whatsapp-agent',
+  name: 'WhatsApp Agent',
+  instructions: 'Answer customer questions and help with tasks in WhatsApp.',
+  model: 'openai/gpt-5.5',
+  channels: {
+    adapters: {
+      whatsapp: createWhatsAppAdapter(),
+    },
+  },
+})
+```
+
+Register the agent on the Mastra instance:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { whatsappAgent } from './agents/whatsapp-agent'
+
+export const mastra = new Mastra({
+  agents: { whatsappAgent },
+})
+```
+
+## Adapter setup
+
+Follow the [Chat SDK WhatsApp adapter docs](https://chat-sdk.dev/adapters/official/whatsapp) for WhatsApp-specific setup, including Meta app configuration, access tokens, phone number IDs, webhook verification, and message limits.
+
+The adapter reads WhatsApp credentials from environment variables such as:
+
+```bash
+WHATSAPP_ACCESS_TOKEN=your-meta-access-token
+WHATSAPP_APP_SECRET=your-meta-app-secret
+WHATSAPP_PHONE_NUMBER_ID=your-whatsapp-phone-number-id
+WHATSAPP_VERIFY_TOKEN=your-webhook-verify-token
+```
+
+## Webhook URL
+
+Mastra generates the WhatsApp webhook route from the agent ID and adapter key:
+
+```text
+/api/agents/whatsapp-agent/channels/whatsapp/webhook
+```
+
+Use your public Mastra server URL as the base URL:
+
+```text
+https://your-app.example.com/api/agents/whatsapp-agent/channels/whatsapp/webhook
+```
+
+Use this URL for incoming WhatsApp event delivery. The generated Mastra route handles POST events from WhatsApp; follow the Chat SDK WhatsApp adapter docs for the Meta callback and webhook verification flow.
+
+## Related
+
+- [Channels overview](https://mastra.ai/docs/capabilities/channels/overview)
+- [More](https://mastra.ai/docs/capabilities/channels/other-adapters)

package/.docs/docs/deployment/mastra-server.md

@@ -14,9 +14,7 @@ Run the build command from your project root:
 mastra build
 ```
 
-This creates a `.mastra` directory containing your production-ready server.
-
-> **Info:** Read the [`mastra build`](https://mastra.ai/reference/cli/mastra) reference for all available flags.
+This creates a `.mastra` directory containing your production-ready server. Read the [`mastra build`](https://mastra.ai/reference/cli/mastra) reference for all available flags.
 
 ## Build output
 
@@ -59,7 +57,7 @@ The `mastra start` command provides additional features:
 - Provides helpful error messages for missing modules
 - Handles process signals for graceful shutdown
 
-> **Info:** Read the [`mastra start`](https://mastra.ai/reference/cli/mastra) reference for all available flags.
+Read the [`mastra start`](https://mastra.ai/reference/cli/mastra) reference for all available flags.
 
 ## Build configuration
 

package/.docs/docs/editor/overview.md

@@ -64,9 +64,7 @@ export const mastra = new Mastra({
 })
 ```
 
-Once registered, you can manage agents through [Studio](https://mastra.ai/docs/studio/overview) or programmatically through the server API and Client SDK.
-
-> **Note:** See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for all configuration options.
+Once registered, you can manage agents through [Studio](https://mastra.ai/docs/studio/overview) or programmatically through the server API and Client SDK. See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for all configuration options.
 
 ## Code and database sources
 
@@ -173,9 +171,7 @@ Because stored agents are data, you can build automation loops that tune agents
 - Re-run the experiment against the draft and compare scores to the baseline.
 - Promote the draft to the published version when the scores improve.
 
-This turns agent tuning into a closed feedback loop. One agent owns the production configuration, another agent iterates on it, and every change is versioned so you can roll back if a round of automated edits makes things worse. Combine this with [version targeting](#version-targeting-and-experimentation) to keep production traffic on the published version while the draft is being tested.
-
-> **Note:** See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for the full namespace API.
+This turns agent tuning into a closed feedback loop. One agent owns the production configuration, another agent iterates on it, and every change is versioned so you can roll back if a round of automated edits makes things worse. Combine this with [version targeting](#version-targeting-and-experimentation) to keep production traffic on the published version while the draft is being tested. See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for the full namespace API.
 
 ## What can be overridden
 

package/.docs/docs/editor/prompts.md

@@ -122,7 +122,7 @@ await editor.agent.update({
 })
 ```
 
-> **Note:** See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for the full `editor.prompt` API.
+See the [MastraEditor reference](https://mastra.ai/reference/editor/mastra-editor) for the full `editor.prompt` API.
 
 ## Versioning
 

package/.docs/docs/editor/tools.md

@@ -142,9 +142,7 @@ When an agent runs, tools from all sources are merged in this order:
 2. Integration tools
 3. MCP tools
 
-If a tool ID exists in multiple sources, later sources take precedence. Description overrides set at the agent level always take priority over the original tool description.
-
-> **Note:** See the [ToolProvider reference](https://mastra.ai/reference/editor/tool-provider) for the full provider API.
+If a tool ID exists in multiple sources, later sources take precedence. Description overrides set at the agent level always take priority over the original tool description. See the [ToolProvider reference](https://mastra.ai/reference/editor/tool-provider) for the full provider API.
 
 ## Related
 

package/.docs/docs/evals/built-in-scorers.md

@@ -54,12 +54,12 @@ These scorers evaluate adherence to format, style, and safety requirements:
 Zero-LLM micro-scorers for fast, deterministic assertions. See the [Quick Checks](https://mastra.ai/docs/evals/quick-checks) guide for usage details.
 
 - [`checks.includes`](https://mastra.ai/reference/evals/checks): Scores 1 if output contains a substring (`0` or `1`)
-- [`checks.excludes`](https://mastra.ai/reference/evals/checks): Scores 1 if output does not contain a substring (`0` or `1`)
+- [`checks.excludes`](https://mastra.ai/reference/evals/checks): Scores 1 if output doesn't contain a substring (`0` or `1`)
 - [`checks.equals`](https://mastra.ai/reference/evals/checks): Scores 1 if output exactly matches a string (`0` or `1`)
 - [`checks.matches`](https://mastra.ai/reference/evals/checks): Scores 1 if output matches a regex (`0` or `1`)
 - [`checks.similarity`](https://mastra.ai/reference/evals/checks): String similarity via Dice coefficient (`0-1`, or binary with threshold)
 - [`checks.calledTool`](https://mastra.ai/reference/evals/checks): Scores 1 if a tool was called at least N times (`0` or `1`)
-- [`checks.didNotCall`](https://mastra.ai/reference/evals/checks): Scores 1 if a tool was not called (`0` or `1`)
+- [`checks.didNotCall`](https://mastra.ai/reference/evals/checks): Scores 1 if a tool wasn't called (`0` or `1`)
 - [`checks.toolOrder`](https://mastra.ai/reference/evals/checks): Scores 1 if tools were called in order (`0` or `1`)
 - [`checks.maxToolCalls`](https://mastra.ai/reference/evals/checks): Scores 1 if tool call count is within limit (`0` or `1`)
 - [`checks.usedNoTools`](https://mastra.ai/reference/evals/checks): Scores 1 if no tools were called (`0` or `1`)

package/.docs/docs/evals/custom-scorers.md

@@ -341,9 +341,7 @@ A custom scorer in Mastra uses `createScorer` with four core components:
 3. [**Score Generation**](#score-generation)
 4. [**Reason Generation**](#reason-generation)
 
-Together, these components allow you to define custom evaluation logic using LLMs as judges.
-
-> **Info:** Visit [createScorer](https://mastra.ai/reference/evals/create-scorer) for the full API and configuration options.
+Together, these components allow you to define custom evaluation logic using LLMs as judges. Visit [createScorer](https://mastra.ai/reference/evals/create-scorer) for the full API and configuration options.
 
 ```typescript
 import { createScorer } from '@mastra/core/evals'

package/.docs/docs/evals/datasets/overview.md

@@ -41,7 +41,7 @@ const existing = await datasets.get({ id: 'dataset-id' })
 const { datasets: all } = await datasets.list()
 ```
 
-> **Info:** Visit the [`DatasetsManager` reference](https://mastra.ai/reference/datasets/datasets-manager) for the full list of methods.
+Visit the [`DatasetsManager` reference](https://mastra.ai/reference/datasets/datasets-manager) for the full list of methods.
 
 ## Studio
 
@@ -196,13 +196,12 @@ Fetch the exact items that existed at a past version:
 const items = await dataset.listItems({ version: 2 })
 ```
 
-You can also pin experiments to a version, see [running experiments](https://mastra.ai/docs/evals/datasets/running-experiments).
-
-> **Info:** Visit the [`Dataset` reference](https://mastra.ai/reference/datasets/dataset) for the full list of methods and parameters.
+You can also pin experiments to a version, see [running experiments](https://mastra.ai/docs/evals/datasets/running-experiments). Visit the [`Dataset` reference](https://mastra.ai/reference/datasets/dataset) for the full list of methods and parameters.
 
 ## Related
 
 - [Running experiments](https://mastra.ai/docs/evals/datasets/running-experiments)
 - [Scorers overview](https://mastra.ai/docs/evals/overview)
 - [DatasetsManager reference](https://mastra.ai/reference/datasets/datasets-manager)
-- [Dataset reference](https://mastra.ai/reference/datasets/dataset)
+- [Dataset reference](https://mastra.ai/reference/datasets/dataset)
+- 📹 [Mastra evals, datasets, and experiments workshop](https://www.youtube.com/watch?v=Vla5LfmOOrM)

package/.docs/docs/evals/datasets/running-experiments.md

@@ -127,7 +127,7 @@ for (const item of summary.results) {
 }
 ```
 
-> **Info:** Visit the [Scorers overview](https://mastra.ai/docs/evals/overview) for details on available and custom scorers.
+Visit the [Scorers overview](https://mastra.ai/docs/evals/overview) for details on available and custom scorers.
 
 ## Tool mocks
 
@@ -154,11 +154,11 @@ Tool mocks are supported for `agent` targets only.
 
 Arguments are matched strictly: object key order is ignored, array order is significant, and there is no type coercion. A mock is served only when the agent calls the tool with arguments that deep-equal the mock's `args`.
 
-When an item declares several mocks for the same tool and arguments, they are consumed in order — the first call gets the first mock, the next call gets the second, and so on. Ordering is tracked per `(toolName, args)` group and is independent across different arguments.
+When an item declares several mocks for the same tool and arguments, they're consumed in order — the first call gets the first mock, the next call gets the second, and so on. Ordering is tracked per `(toolName, args)` group and is independent across different arguments.
 
 ### Matching mode
 
-By default each mock matches strictly on its `args`. Set `matchArgs: 'ignore'` to match on the tool name only — the mock's `args` are not compared and the next unconsumed mock for that tool is served regardless of how the agent called it:
+By default each mock matches strictly on its `args`. Set `matchArgs: 'ignore'` to match on the tool name only — the mock's `args` aren't compared and the next unconsumed mock for that tool is served regardless of how the agent called it:
 
 ```typescript
 const subAgentMock = {
@@ -173,12 +173,12 @@ This is useful when a tool's arguments are noisy or generated by the model. The
 
 ### Failures
 
-A mocked tool call fails the item when the arguments do not match or all matching mocks have been consumed:
+A mocked tool call fails the item when the arguments don't match or all matching mocks have been consumed:
 
 - `TOOL_MOCK_MISMATCH` — the tool was called with arguments that no mock matches.
 - `TOOL_MOCK_EXHAUSTED` — every matching mock has already been consumed.
 
-When a mocked tool is mis-called, the agent run is aborted immediately, so the model cannot go on to call any further tools — including unmocked, side-effecting tools that would otherwise run live. These failures are deterministic, so they are not retried. Mocks that are declared but never used do not fail the item — they are reported as unconsumed.
+When a mocked tool is mis-called, the agent run is aborted immediately, so the model can't go on to call any further tools — including unmocked, side-effecting tools that would otherwise run live. These failures are deterministic, so they're not retried. Mocks that are declared but never used don't fail the item — they're reported as unconsumed.
 
 While an item has mocks, the agent's tools execute sequentially so repeated `(toolName, args)` mocks are consumed in the provider's call order. This serialization applies only to items that declare mocks.
 
@@ -202,8 +202,8 @@ In [Studio](https://mastra.ai/docs/studio/overview), edit a dataset item to auth
 
 ### Limitations
 
-- **No tool span for mocked calls.** A mocked call returns its output before the tool executes, so it does not create a tool span. Trajectory scorers backed by stored traces may therefore not see mocked tool calls. Trajectory extraction that falls back to the agent's message output still sees them, so trajectory scoring can differ depending on your observability configuration.
-- **Storage support.** Tool mocks and tool mock reports are persisted by the LibSQL, PostgreSQL, MongoDB, and Spanner adapters. The MySQL adapter does not support them and rejects writes that carry tool mocks or a tool mock report so the feature never silently runs tools live.
+- **No tool span for mocked calls.** A mocked call returns its output before the tool executes, so it doesn't create a tool span. Trajectory scorers backed by stored traces may therefore not see mocked tool calls. Trajectory extraction that falls back to the agent's message output still sees them, so trajectory scoring can differ depending on your observability configuration.
+- **Storage support.** Tool mocks and tool mock reports are persisted by the LibSQL, PostgreSQL, MongoDB, and Spanner adapters. The MySQL adapter doesn't support them and rejects writes that carry tool mocks or a tool mock report so the feature never silently runs tools live.
 
 ## Async experiments
 
@@ -321,6 +321,8 @@ console.log(experiment.startedAt)
 console.log(experiment.completedAt)
 ```
 
+> **📹 Watch:** Watch [Mastra datasets and experiments workflow](https://www.youtube.com/watch?v=R6pjAdGhxhQ) to see how datasets and experiments help improve reliability.
+
 ### Item-level results
 
 ```typescript
@@ -342,7 +344,7 @@ for (const result of results) {
 - `completedWithErrors` is `true` when the experiment finished but some items failed.
 - Items cancelled via `signal` appear in `skippedCount`.
 
-> **Info:** Visit the [`startExperiment` reference](https://mastra.ai/reference/datasets/startExperiment) for the full parameter and return type documentation.
+Visit the [`startExperiment` reference](https://mastra.ai/reference/datasets/startExperiment) for the full parameter and return type documentation.
 
 ## Related
 

package/.docs/docs/evals/evals-with-memory.md

@@ -136,9 +136,7 @@ const summary = await dataset.startExperiment({
 })
 ```
 
-The inline `task` receives the item's `metadata`, so each row can drive its own thread without changing the agent or any scorer.
-
-> **Note:** Visit [runEvals reference](https://mastra.ai/reference/evals/run-evals) and [Dataset reference](https://mastra.ai/reference/datasets/dataset) for full configuration.
+The inline `task` receives the item's `metadata`, so each row can drive its own thread without changing the agent or any scorer. Visit [runEvals reference](https://mastra.ai/reference/evals/run-evals) and [Dataset reference](https://mastra.ai/reference/datasets/dataset) for full configuration.
 
 ## Related
 

package/.docs/docs/evals/gates-and-verdicts.md

@@ -64,9 +64,7 @@ const result = await runEvals({
 // result.gateResults: [{ id: 'check-called-tool', passed: true, score: 1 }]
 ```
 
-Any scorer works as a gate. Quick Checks are a natural fit because they return binary 1/0 scores.
-
-> **Note:** Visit [runEvals() reference](https://mastra.ai/reference/evals/run-evals) for the full parameter and return type documentation.
+Any scorer works as a gate. Quick Checks are a natural fit because they return binary 1/0 scores. Visit [runEvals() reference](https://mastra.ai/reference/evals/run-evals) for the full parameter and return type documentation.
 
 ## Thresholds
 
@@ -101,7 +99,7 @@ const result = await runEvals({
 // ]
 ```
 
-A bare scorer (no threshold) still appears in `result.scores` but does not affect the verdict.
+A bare scorer (no threshold) still shows up in `result.scores` but doesn't affect the verdict.
 
 ## Using verdicts in CI
 

package/.docs/docs/evals/overview.md

@@ -8,6 +8,8 @@ Scorers are automated tests that evaluate Agents outputs using model-graded, rul
 
 Scorers can be run in the cloud, capturing real-time results. But scorers can also be part of your CI/CD pipeline, allowing you to test and monitor your agents over time.
 
+> **📹 Watch:** Watch [Mastra evals overview](https://www.youtube.com/watch?v=12WN6u2DrBk) for an introduction to evals and how to reason about agent quality.
+
 ## Types of scorers
 
 Mastra provides different kinds of scorers, each serving a specific purpose. Here are some common types:
@@ -142,4 +144,5 @@ Once registered, you can score traces interactively within Studio under the **Ob
 - Add [gates and verdicts](https://mastra.ai/docs/evals/gates-and-verdicts) to enforce hard requirements and quality thresholds
 - Learn how to create your own scorers in the [Creating Custom Scorers](https://mastra.ai/docs/evals/custom-scorers) guide
 - Explore built-in scorers in the [Built-in Scorers](https://mastra.ai/docs/evals/built-in-scorers) section
-- Test scorers with [Studio](https://mastra.ai/docs/studio/overview)
+- Test scorers with [Studio](https://mastra.ai/docs/studio/overview)
+- 📹 [Mastra evals workshop](https://www.youtube.com/watch?v=OHOZ5PgPj5M\&t=3578s)

package/.docs/docs/evals/quick-checks.md

@@ -44,7 +44,7 @@ These scorers evaluate the agent's text output:
 | Check                    | What it does                          | Score                            |
 | ------------------------ | ------------------------------------- | -------------------------------- |
 | `checks.includes(str)`   | Output contains substring             | 1 or 0                           |
-| `checks.excludes(str)`   | Output does not contain substring     | 1 or 0                           |
+| `checks.excludes(str)`   | Output doesn't contain substring      | 1 or 0                           |
 | `checks.equals(str)`     | Output exactly equals string          | 1 or 0                           |
 | `checks.matches(regex)`  | Output matches regular expression     | 1 or 0                           |
 | `checks.similarity(str)` | Dice coefficient similarity to string | 0-1 (or binary with `threshold`) |
@@ -56,7 +56,7 @@ These scorers evaluate tool usage from the agent's run:
 | Check                     | What it does                     | Score  |
 | ------------------------- | -------------------------------- | ------ |
 | `checks.calledTool(name)` | Tool was called at least N times | 1 or 0 |
-| `checks.didNotCall(name)` | Tool was not called              | 1 or 0 |
+| `checks.didNotCall(name)` | Tool wasn't called               | 1 or 0 |
 | `checks.toolOrder([...])` | Tools called in expected order   | 1 or 0 |
 | `checks.maxToolCalls(n)`  | No more than N tool calls total  | 1 or 0 |
 | `checks.usedNoTools()`    | No tools called at all           | 1 or 0 |
@@ -127,9 +127,7 @@ Each check is a standard `createScorer()` instance with a `preprocess` step and
 1. **preprocess**: Extracts and normalizes relevant data from the agent run (text content, tool calls)
 2. **generateScore**: Converts the preprocessed result into a score (typically binary 1 or 0)
 
-Because checks skip the `analyze` and `generateReason` steps and make no LLM calls, they run in microseconds.
-
-> **Note:** Visit the [Quick Checks reference](https://mastra.ai/reference/evals/checks) for the full API, including all parameters and options for each check.
+Because checks skip the `analyze` and `generateReason` steps and make no LLM calls, they run in microseconds. Visit the [Quick Checks reference](https://mastra.ai/reference/evals/checks) for the full API, including all parameters and options for each check.
 
 ## Related
 

package/.docs/docs/getting-started/file-based-agents.md

@@ -0,0 +1,114 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# File-based agents
+
+**Added in:** `@mastra/core@1.50.0`
+
+> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+
+File-based agents are a new, convention-based way to define Mastra agents and project primitives from a directory structure under `src/mastra/`. You'll like this approach if you want an agent to be self-contained, easy to scan and extend.
+
+Adopting this feature is a fundamental decision about how to structure your project. You'll need to follow the file conventions and be aware of its limitations, namely that you can't use dynamic configuration or runtime wiring.
+
+However, you can use file-based agents, code-defined agents, or both in the same project. All Mastra docs currently use code-first examples. As file-based agents mature, more examples may use this structure where it makes sense.
+
+Under the hood Mastra is assembling code-defined agents and primitives from the files you create. So explanations and concepts you can find on other docs pages apply to file-based agents as well.
+
+## Basic layout
+
+A small file-based agent looks like this:
+
+```text
+src/mastra/
+  agents/
+    weather/
+      config.ts
+      instructions.md
+      tools/
+        get-weather.ts
+      skills/
+        forecast-review.md
+```
+
+The main files in an agent directory are:
+
+- [`config.ts`](https://mastra.ai/reference/file-based-agents/config): Model selection and runtime options
+- [`instructions.md`](https://mastra.ai/reference/file-based-agents/instructions): The prompt that applies to every response
+- [`tools/`](https://mastra.ai/reference/file-based-agents/tools): Typed functions the model can call
+- [`skills/`](https://mastra.ai/reference/file-based-agents/skills): Reusable instructions
+
+You need to define `config.ts` and `instructions.md` at a minimum. Add optional files as needed. Learn more in the [add capabilities](#add-capabilities) section.
+
+## Quickstart
+
+Create a folder at `src/mastra/agents/weather`. Inside, add a `config.ts` and an `instructions.md` file with these contents:
+
+```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.
+```
+
+Start Mastra's development server with `mastra dev`. Inside Studio, you can now call the `weather` agent and ask it about the weather.
+
+## Add capabilities
+
+Map each primitive or feature to its file convention:
+
+| Primitive or feature                                                             | File convention                                                                           |
+| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| [Agent config](https://mastra.ai/reference/file-based-agents/config)             | `src/mastra/agents/<agent-id>/config.ts`                                                  |
+| [Agent instructions](https://mastra.ai/reference/file-based-agents/instructions) | `src/mastra/agents/<agent-id>/instructions.md`                                            |
+| [Tools](https://mastra.ai/reference/file-based-agents/tools)                     | `src/mastra/agents/<agent-id>/tools/`                                                     |
+| [Skills](https://mastra.ai/reference/file-based-agents/skills)                   | `src/mastra/agents/<agent-id>/skills/`                                                    |
+| [Memory](https://mastra.ai/reference/file-based-agents/memory)                   | `src/mastra/agents/<agent-id>/memory.ts`                                                  |
+| [Workspace](https://mastra.ai/reference/file-based-agents/workspace)             | `src/mastra/agents/<agent-id>/workspace.ts` and `src/mastra/agents/<agent-id>/workspace/` |
+| [Processors](https://mastra.ai/reference/file-based-agents/processors)           | `src/mastra/agents/<agent-id>/processors/`                                                |
+| [Subagents](https://mastra.ai/reference/file-based-agents/subagents)             | `src/mastra/agents/<agent-id>/subagents/`                                                 |
+| [Workflows](https://mastra.ai/reference/file-based-agents/workflows)             | `src/mastra/workflows/`                                                                   |
+| [Storage](https://mastra.ai/reference/file-based-agents/storage)                 | `src/mastra/storage.ts`                                                                   |
+| [Observability](https://mastra.ai/reference/file-based-agents/observability)     | `src/mastra/observability.ts`                                                             |
+| [Server config](https://mastra.ai/reference/file-based-agents/server)            | `src/mastra/server.ts`                                                                    |
+| [Studio config](https://mastra.ai/reference/file-based-agents/studio)            | `src/mastra/studio.ts`                                                                    |
+
+## Discovery lifecycle
+
+File-based primitives are discovered by the Mastra bundler under `mastra dev` and `mastra build`. During discovery, Mastra reads supported files under `src/mastra/`, imports TypeScript and JavaScript modules, reads markdown instructions and skills, copies workspace seed files, and registers the assembled primitives with your Mastra app.
+
+After discovery, a file-based agent runs as a normal [`Agent`](https://mastra.ai/reference/agents/agent). Calling it from the Agent API, Studio, workflows, or your application code uses the same runtime as a code-defined agent.
+
+Discovery is source-based and conservative. It skips symlinks, ignores test files, treats workflows and singleton project files as file-routed only when they have a default export, and ignores directories that aren't agent directories.
+
+Start your app through the Mastra CLI so discovery runs:
+
+**npm**:
+
+```bash
+npx mastra dev
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx mastra dev
+```
+
+**Yarn**:
+
+```bash
+yarn dlx mastra dev
+```
+
+**Bun**:
+
+```bash
+bun x mastra dev
+```
+
+If you import your `mastra` instance directly, `agents/<name>/` directories and the other conventions aren't discovered. When you consume Mastra as a library, register those primitives in code instead.

package/.docs/docs/getting-started/manual-install.md

@@ -2,9 +2,11 @@
 
 # Manual install
 
-**For AI agents:** Use this guide when tasked to create a runnable Mastra project from scratch without a CLI/boilerplate. It provides code examples for agents, tools, model configuration and how to install dependencies. Do not navigate to the quickstart guide, which is for humans.
+**For AI agents:** Use this guide when tasked to create a runnable Mastra project from scratch without a CLI/boilerplate. It provides code examples for agents, tools, model configuration and how to install dependencies. Do not navigate to the quickstart guide, which is for humans. The model string is Mastra's model router format ('provider/model'; use / and not : to separate provider and model). Do not install any ai-sdk packages.
 
-> **Info:** Use this guide to manually build a standalone Mastra server step by step. In most cases, it's quicker to follow the [quickstart guide](https://mastra.ai/guides/getting-started/quickstart), which achieves the same result using the [`mastra create`](https://mastra.ai/reference/cli/create-mastra) command. For existing projects, you can also use [`mastra init`](https://mastra.ai/reference/cli/mastra).
+Use this guide to manually build a standalone Mastra server step by step. In most cases, it's quicker to follow the [quickstart guide](https://mastra.ai/guides/getting-started/quickstart), which achieves the same result using the [`mastra create`](https://mastra.ai/reference/cli/create-mastra) command. For existing projects, you can also use [`mastra init`](https://mastra.ai/reference/cli/mastra).
+
+## Instructions
 
 If you prefer not to use our automatic CLI tool, you can set up your project yourself by following the guide below.
 
@@ -163,7 +165,7 @@ If you prefer not to use our automatic CLI tool, you can set up your project you
    mkdir -p src/mastra/agents && touch src/mastra/agents/weather-agent.ts
    ```
 
-   Use `import { Agent } from "@mastra/core/agent"`. Constructor takes `{ id, name, instructions, model: 'openai/gpt-5.5' }`. The model string is Mastra's model router format ('provider/model'; use / and not : to separate provider and model). Do not install any ai-sdk package unless Mastra's documentation says otherwise.
+   Use `import { Agent } from "@mastra/core/agent"`. Constructor takes `{ id, name, instructions, model: 'openai/gpt-5.5' }`. The model string is Mastra's model router format ('provider/model'; use / and not : to separate provider and model). Do not install any ai-sdk packages.
 
    Add the following code:
 
@@ -234,4 +236,15 @@ If you prefer not to use our automatic CLI tool, you can set up your project you
 
    ```bash
    bun run dev
-   ```
+   ```
+
+   **For AI agents:** To validate your work, run a build and do a typecheck with `tsc --noEmit`.
+
+## Next steps
+
+- [Review the project structure](https://mastra.ai/reference/project-structure): Understand how `src/mastra/` files map to agents, tools, workflows, storage, and configuration.
+- [Test your agent in Studio](https://mastra.ai/docs/studio/overview): Open the local Studio UI and run the weather agent.
+- [Use tools with agents](https://mastra.ai/docs/agents/using-tools): Replace the example weather tool with a real tool that calls an API or service.
+- [Add memory](https://mastra.ai/docs/memory/overview): Persist conversation history and user-specific context.
+- [Configure storage](https://mastra.ai/docs/storage/overview): Add a persistent storage adapter for memory, workflows, observability, and other runtime state.
+- [Build and deploy](https://mastra.ai/docs/deployment/overview): Build the Mastra server and deploy it to a hosting platform.

package/.docs/docs/index.md

@@ -54,7 +54,7 @@ export const weatherTool = createTool({
 })
 ```
 
-If you need to create an agent, create a new file and use `import { Agent } from "@mastra/core/agent"`. The constructor takes `{ id, name, instructions, model }`. The `model` property is a string in Mastra's model router format: `provider/model`, for example `openai/gpt-5.5`. For OpenAI models, use `openai/<model>`, not `openai:<model>`, and don't pass a provider object. No provider import is needed for this format. Do not install any AI SDK package unless Mastra's documentation says otherwise.
+If you need to create an agent, create a new file and use `import { Agent } from "@mastra/core/agent"`. The constructor takes `{ id, name, instructions, model }`. The `model` property is a string in Mastra's model router format: `provider/model`, for example `openai/gpt-5.5`. For OpenAI models, use `openai/<model>`, not `openai:<model>`, and don't pass a provider object. No provider import is needed for this format. Don't install any AI SDK package unless Mastra's documentation says otherwise.
 
 Add a tool an agent by importing the tool and passing it to the agent constructor as a tools object.
 

package/.docs/docs/long-running-agents/background-tasks.md

@@ -16,7 +16,7 @@ Use background tasks when a tool call may take long enough that the user shouldn
 
 For tool calls that return quickly, foreground execution using `agent.stream()` and `agent.generate()` is simpler.
 
-> **Note:** Background tasks require a configured [storage](https://mastra.ai/docs/memory/storage) backend on the Mastra instance. Tasks are persisted so they survive process restarts.
+> **Note:** Background tasks require a configured [storage](https://mastra.ai/docs/storage/overview) backend on the Mastra instance. Tasks are persisted so they survive process restarts.
 
 ## Quickstart
 
@@ -168,7 +168,7 @@ const stream = await agent.stream('Research solana for me', {
 })
 ```
 
-> **Note:** Visit [`Agent.stream()`](https://mastra.ai/reference/streaming/agents/stream) for the full API.
+Visit [`Agent.stream()`](https://mastra.ai/reference/streaming/agents/stream) for the full API.
 
 ### Aggregate properties
 
@@ -379,4 +379,4 @@ These read from storage rather than the pubsub stream, so they're suitable for p
 - [Durable agents](https://mastra.ai/docs/long-running-agents/durable-agents)
 - [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)
 - [Stream chunk types](https://mastra.ai/reference/streaming/ChunkType)
-- [Storage](https://mastra.ai/docs/memory/storage)
+- [Storage](https://mastra.ai/docs/storage/overview)

package/.docs/docs/long-running-agents/durable-agents.md

@@ -60,9 +60,7 @@ for await (const chunk of output.fullStream) {
 cleanup()
 ```
 
-The returned `runId` identifies the execution. Pass it to `observe()` to reconnect from a different client.
-
-> **Note:** Visit the [DurableAgent reference](https://mastra.ai/reference/agents/durable-agent) for the full configuration and method API.
+The returned `runId` identifies the execution. Pass it to `observe()` to reconnect from a different client. Visit the [DurableAgent reference](https://mastra.ai/reference/agents/durable-agent) for the full configuration and method API.
 
 ## How it works
 
@@ -105,7 +103,7 @@ export const durableHelper = createDurableAgent({ agent })
 
 ### Fire-and-forget with `createEventedAgent()`
 
-The workflow starts in the background without blocking the caller. You still receive chunks through PubSub, so `stream()` returns a result you can consume. The HTTP handler that triggered the run does not need to wait for the workflow to finish:
+The workflow starts in the background without blocking the caller. You still receive chunks through PubSub, so `stream()` returns a result you can consume. The HTTP handler that triggered the run doesn't need to wait for the workflow to finish:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -140,7 +138,7 @@ const agent = new Agent({
 export const inngestAnalyst = createInngestAgent({ agent, inngest })
 ```
 
-> **Note:** Visit the [`createInngestAgent()` reference](https://mastra.ai/reference/agents/inngest-agent) for the full API, including Inngest-specific options like PubSub and cache configuration.
+Visit the [`createInngestAgent()` reference](https://mastra.ai/reference/agents/inngest-agent) for the full API, including Inngest-specific options like PubSub and cache configuration.
 
 ## Resumable streams
 
@@ -170,7 +168,7 @@ export const durableAgent = createDurableAgent({
 })
 ```
 
-`createInngestAgent()` does not enable caching by default. Pass a `cache` option or register the agent with a `Mastra` instance that has a `serverCache` configured to enable resumable streams.
+`createInngestAgent()` doesn't enable caching by default. Pass a `cache` option or register the agent with a `Mastra` instance that has a `serverCache` configured to enable resumable streams.
 
 ## Streaming with background tasks
 
@@ -199,7 +197,7 @@ await durableAgent.stream('Research topic', {
 })
 ```
 
-> **Note:** Visit [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks) for the full background task guide, including configuration, subagents, and suspend/resume.
+Visit [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks) for the full background task guide, including configuration, subagents, and suspend/resume.
 
 ## Cleanup