@mastra/mcp-docs-server 1.2.7-alpha.12 → 1.2.7-alpha.3

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

@@ -1,26 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Logger
-
-Mastra sets the project's [logger](https://mastra.ai/docs/observability/logging) from a `logger.ts` file directly under `src/mastra/`. The file default-exports a logger, which replaces the built-in `ConsoleLogger` used across agents, workflows, and other components.
-
-Use this page for the file-based convention. For log levels, transports, and provider details, see [logging](https://mastra.ai/docs/observability/logging).
-
-## Quickstart
-
-Create `src/mastra/logger.ts` and default-export a logger, such as [`PinoLogger`](https://mastra.ai/reference/logging/pino-logger):
-
-```typescript
-import { PinoLogger } from '@mastra/loggers'
-
-export default new PinoLogger({
-  name: 'Mastra',
-  level: 'info',
-})
-```
-
-Mastra registers the logger before storage, observability, and file-based agents, so those primitives log through this logger as they are wired up.
-
-## Precedence with code
-
-Code-registered logging wins over `logger.ts`. If you pass `logger` to `new Mastra({ logger })` in `src/mastra/index.ts` (or set `logger: false` to disable logging), `logger.ts` is ignored with a warning. Use `logger.ts` when one project-wide logger is enough; use code registration when setup depends on runtime wiring.

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

@@ -1,58 +0,0 @@
-> 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.

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

@@ -1,32 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Observability
-
-Mastra configures [observability](https://mastra.ai/docs/observability/overview) from an `observability.ts` file directly under `src/mastra/`. The file default-exports an `Observability` instance that sets up tracing, logging, metrics, and feedback for the project.
-
-Use this page for the file-based convention. For the signal model, exporters, storage, and multi-config setup, see [Observability overview](https://mastra.ai/docs/observability/overview) and [Observability configuration](https://mastra.ai/docs/observability/config).
-
-## Quickstart
-
-Create `src/mastra/observability.ts` and default-export an `Observability` instance:
-
-```typescript
-import { MastraStorageExporter, Observability } from '@mastra/observability'
-
-export default new Observability({
-  configs: {
-    default: {
-      serviceName: 'mastra',
-      exporters: [new MastraStorageExporter()],
-    },
-  },
-})
-```
-
-## Observability and storage
-
-`observability.ts` configures which signals are collected and where they're exported. [`storage.ts`](https://mastra.ai/reference/file-based-agents/storage) configures the project store that can persist observability records. For storage support by signal, see [Observability storage](https://mastra.ai/docs/observability/storage).
-
-## Precedence with code
-
-Code-registered observability wins over `observability.ts`. Use `observability.ts` when one project-wide configuration is enough; use code registration when setup depends on runtime wiring in `src/mastra/index.ts`.

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

@@ -1,56 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Processors
-
-A file-based agent discovers [processors](https://mastra.ai/docs/agents/processors) from its `processors/` directory. Use this page for the file-based convention; use the processors guide for built-in processors, custom processors, streaming behavior, and advanced patterns.
-
-Files under `processors/input/` run before messages reach the model. Files under `processors/output/` run after the model responds. Each file default-exports one [`Processor`](https://mastra.ai/reference/processors/processor-interface), and the filename becomes its discovery key.
-
-## Quickstart
-
-Add an input processor by placing a processor file under `processors/input/`:
-
-```typescript
-import { PIIDetector } from '@mastra/core/processors'
-
-export default new PIIDetector({
-  strategy: 'block',
-})
-```
-
-This processor runs before user messages reach the model.
-
-## Add an output processor
-
-Output processors are good for filtering or transforming model responses before they're returned. This example redacts PII from the final response.
-
-```typescript
-import { PIIDetector } from '@mastra/core/processors'
-
-export default new PIIDetector({
-  strategy: 'redact',
-})
-```
-
-## Ordering
-
-Discovered processors are added after any processors defined in [`config.ts`](https://mastra.ai/reference/file-based-agents/config). That means config processors run first.
-
-```text
-config.inputProcessors → processors/input/* → model
-model → config.outputProcessors → processors/output/* → response
-```
-
-If `config.inputProcessors` or `config.outputProcessors` is a function, discovered processors of that type are ignored with a warning because function-valued processors can't be statically merged.
-
-## Precedence with config
-
-Use `config.ts` for processors that need to be created dynamically or shared across agents. Use file-based processors for static, per-agent processors that should be reviewed alongside the agent.
-
-Precedence is:
-
-1. Function-valued `config.inputProcessors` or `config.outputProcessors`
-2. Array-valued `config.inputProcessors` or `config.outputProcessors`
-3. Discovered files under `processors/input/` or `processors/output/`
-
-Visit the [`Processor` reference](https://mastra.ai/reference/processors/processor-interface) for the full interface.

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

@@ -1,54 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Scorers
-
-A file-based agent discovers [scorers](https://mastra.ai/docs/evals/overview) from its `scorers/` directory. Use this page for the file-based convention; use the scorers guide for built-in scorers, custom scorers, and sampling.
-
-Each file under `scorers/` default-exports one scorer, and the filename becomes its key. The default export is either a [`MastraScorer`](https://mastra.ai/reference/evals/create-scorer) or a `{ scorer, sampling }` entry.
-
-## Quickstart
-
-Add a scorer by placing a file under the agent's `scorers/` directory. This example uses a [custom scorer](https://mastra.ai/docs/evals/custom-scorers):
-
-```typescript
-import { createScorer } from '@mastra/core/evals'
-
-export default createScorer({
-  id: 'relevance',
-  description: 'Scores how relevant the response is',
-}).generateScore(() => 1)
-```
-
-The scorer is registered on the `weather` agent under the key `relevance`, the same as adding it to `config.scorers`.
-
-## Sampling
-
-To control how often a scorer runs, default-export a `{ scorer, sampling }` entry instead of a bare scorer:
-
-```typescript
-import { createScorer } from '@mastra/core/evals'
-
-const relevance = createScorer({
-  id: 'relevance',
-  description: 'Scores how relevant the response is',
-}).generateScore(() => 1)
-
-export default {
-  scorer: relevance,
-  sampling: { type: 'ratio', rate: 0.5 },
-}
-```
-
-## Precedence with config
-
-Discovered scorers are merged with the scorers defined in [`config.ts`](https://mastra.ai/reference/file-based-agents/config). On a key collision, `config.scorers` wins with a warning. If `config.scorers` is a function, discovered scorers are ignored with a warning because function-valued scorers can't be statically merged.
-
-When keys collide, precedence is:
-
-1. Function-valued `config.scorers`
-2. Record-valued `config.scorers`
-3. Discovered files under `scorers/`
-
-Non-colliding discovered scorers are preserved.
-
-Visit [`createScorer()`](https://mastra.ai/reference/evals/create-scorer) for the full scorer interface.

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

@@ -1,37 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Server
-
-Mastra configures its HTTP [server](https://mastra.ai/docs/server/mastra-server) from a `server.ts` file directly under `src/mastra/`. The server exposes agents, workflows, and other registered primitives as REST endpoints, and the file default-exports the same `ServerConfig` shape you'd pass to [`new Mastra()`](https://mastra.ai/reference/core/mastra-class).
-
-Use this page for the file-based convention. For server features, middleware, custom routes, generated API docs, and deployment behavior, see [Server overview](https://mastra.ai/docs/server/mastra-server).
-
-## Quickstart
-
-Create `src/mastra/server.ts` and default-export a `ServerConfig` object:
-
-```typescript
-import type { ServerConfig } from '@mastra/core/server'
-
-export default {
-  port: 4111,
-  host: '0.0.0.0',
-} satisfies ServerConfig
-```
-
-## Common configurations
-
-`server.ts` can configure the same server options as code registration:
-
-| Need                                  | Use                                       |
-| ------------------------------------- | ----------------------------------------- |
-| Bind to a deployment platform address | `host` and `port`                         |
-| Restrict browser access               | `cors`                                    |
-| Add webhooks or health checks         | `apiRoutes`                               |
-| Enable generated API docs             | `build.openAPIDocs` and `build.swaggerUI` |
-
-See [Mastra server](https://mastra.ai/docs/server/mastra-server), [middleware](https://mastra.ai/docs/server/middleware), and [custom API routes](https://mastra.ai/docs/server/custom-api-routes) for examples.
-
-## Precedence with code
-
-Code-registered server config wins over `server.ts`. Routes added during startup, such as channel webhooks, are preserved when file-based server config is applied.

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

@@ -1,56 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Skills
-
-A file-based agent discovers skills from its `skills/` directory and bundles them at build time. Skills are reusable procedures or reference material that the agent can load when relevant, instead of putting every detail into the always-on prompt.
-
-Use this page for the file-based convention. For code-defined skills, see [Agent skills](https://mastra.ai/docs/agents/skills). For the `SKILL.md` package format, see [Workspace skills](https://mastra.ai/docs/workspace/skills).
-
-## Quickstart
-
-The simplest skill is one markdown file under `skills/`. The filename becomes the skill name, and `description` tells the agent when to load it.
-
-```markdown
----
-description: Use when reporting temperatures or comparing forecast units.
----
-
-Always report temperatures in Celsius and Fahrenheit. Include the user's preferred unit first when known.
-```
-
-## Skills vs tools vs instructions
-
-| Need                                                 | Use                                                                             | Why                                                                  |
-| ---------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| Always-on identity, tone, or rules                   | [`instructions.md`](https://mastra.ai/reference/file-based-agents/instructions) | The model should see the guidance every turn.                        |
-| Callable action with inputs and outputs              | [`tools/`](https://mastra.ai/reference/file-based-agents/tools)                 | The model needs to execute code, call APIs, or perform side effects. |
-| Detailed reference or procedure loaded when relevant | `skills/`                                                                       | The model only needs the full guidance for specific tasks.           |
-
-## Skill formats
-
-Mastra supports three file-based skill formats:
-
-| Format                        | Use it when                                                                                                      |
-| ----------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| TypeScript/JavaScript module  | You want to default-export a [`createSkill()`](https://mastra.ai/reference/agents/createSkill) result from code. |
-| Packaged `SKILL.md` directory | The skill has instructions plus supporting files under `references/`.                                            |
-| Flat markdown file            | The skill is one markdown file with frontmatter and instructions.                                                |
-
-For packaged skills, `description` is required in `SKILL.md` frontmatter. Flat markdown skills also require `description` in frontmatter. Write when to use the skill, not only what the skill contains.
-
-## What gets loaded
-
-File-based Agents skills are read at build time and added to the generated bundle. The deployed agent doesn't need to read those skill files from disk at runtime.
-
-For packaged skills, Mastra reads:
-
-- `SKILL.md` for metadata and instructions.
-- Files directly under `references/` as supporting reference content.
-
-Reference files are keyed by filename. Symlinked files and directories under `references/` are skipped during discovery.
-
-## Precedence with config
-
-Discovered skills merge with any `skills` in [`config.ts`](https://mastra.ai/reference/file-based-agents/config). On a name collision, `config.skills` wins and a warning is logged.
-
-If `config.skills` is a function, discovered skills are ignored with a warning because function-valued skills can't be statically merged.

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

@@ -1,30 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Storage
-
-Mastra sets the project's default [storage](https://mastra.ai/docs/storage/overview) from a `storage.ts` file directly under `src/mastra/`. The file default-exports a store, which replaces the built-in in-memory store used for memory, workflows, observability, and other storage domains.
-
-Use this page for the file-based convention. For backend choice, storage domains, retention, and provider details, see [storage overview](https://mastra.ai/docs/storage/overview).
-
-## Quickstart
-
-Use [`LibSQLStore`](https://mastra.ai/reference/storage/libsql) for a local file-backed store:
-
-```typescript
-import { LibSQLStore } from '@mastra/libsql'
-
-export default new LibSQLStore({
-  id: 'mastra-storage',
-  url: 'file:./mastra.db',
-})
-```
-
-Mastra registers the store before file-based agents and workflows, so storage-dependent primitives bind to this store instead of the default in-memory store.
-
-## Production backends
-
-`storage.ts` can export any Mastra storage adapter, such as LibSQL, PostgreSQL, or MongoDB. For setup patterns, provider support, and schema details, see [storage overview](https://mastra.ai/docs/storage/overview), [observability storage](https://mastra.ai/docs/observability/storage), and the [storage reference](https://mastra.ai/reference/storage/overview).
-
-## Precedence with code
-
-Code-registered storage wins over `storage.ts`. Use `storage.ts` when one project-wide store is enough; use code registration when setup depends on runtime wiring in `src/mastra/index.ts`.

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

@@ -1,56 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Studio
-
-Mastra configures [Studio](https://mastra.ai/docs/studio/overview) from a `studio.ts` file directly under `src/mastra/`. The file default-exports a `StudioConfig` object for Studio authentication and authorization: who can access Studio, and what authenticated users can do.
-
-Use this page for the file-based convention. For auth providers, role-based access control (RBAC), and fine-grained authorization (FGA), see [Studio auth](https://mastra.ai/docs/studio/auth).
-
-## Quickstart
-
-For local development, you don't need `studio.ts`. Start the dev server and open Studio:
-
-**npm**:
-
-```bash
-npm run dev
-```
-
-**pnpm**:
-
-```bash
-pnpm run dev
-```
-
-**Yarn**:
-
-```bash
-yarn dev
-```
-
-**Bun**:
-
-```bash
-bun run dev
-```
-
-Studio opens without authentication in local development. Add `studio.ts` when you're ready to secure a shared or production deployment.
-
-## Add authentication
-
-Use an auth provider to require sign-in before users can access Studio. This example uses [WorkOS](https://mastra.ai/docs/server/auth/workos):
-
-```typescript
-import { MastraAuthWorkos } from '@mastra/auth-workos'
-import type { StudioConfig } from '@mastra/core/server'
-
-export default {
-  auth: new MastraAuthWorkos(),
-} satisfies StudioConfig
-```
-
-The auth provider handles who the user is. For what the user can do after sign-in, add RBAC or FGA in the same config. See [Studio auth](https://mastra.ai/docs/studio/auth) for full examples.
-
-## Precedence with code
-
-Code-registered Studio config wins over `studio.ts`. Use `studio.ts` when one project-wide Studio config is enough; use code registration when auth depends on runtime wiring in `src/mastra/index.ts`.

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

@@ -1,123 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Subagents
-
-A file-based agent can declare **subagents**, specialist child agents it delegates to. The parent model sees each subagent as a delegation tool named after the subagent directory, calls that tool to hand off a task, and receives the subagent's result back in the parent conversation.
-
-Use this page for the file-based convention. For broader delegation patterns, hooks, memory isolation, tool approval propagation, and scoring, see [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents).
-
-## Quickstart
-
-Declare one directory per subagent under `subagents/`:
-
-```text
-src/mastra/agents/
-└── supervisor/
-    ├── config.ts
-    ├── instructions.md
-    └── subagents/
-        └── researcher/
-            ├── config.ts
-            ├── instructions.md
-            └── tools/
-                └── search.ts
-```
-
-Mastra assembles `researcher` as its own agent and wires it into the supervisor's `agents` map. The parent model can delegate to it by using the generated `researcher` delegation tool.
-
-A subagent's `config.ts` must set a non-empty `description`. The parent model reads this when deciding whether to delegate.
-
-```typescript
-import { agentConfig } from '@mastra/core/agent'
-
-export default agentConfig({
-  model: 'openai/gpt-5.5',
-  description: 'Researches a topic and returns cited findings.',
-})
-```
-
-## How the model delegates
-
-A subagent's `description` is routing text for the parent model. Write it like a [tool description](https://mastra.ai/reference/file-based-agents/tools): explain what the subagent does and when to delegate to it.
-
-The build fails when a discovered subagent doesn't provide a non-empty description.
-
-## Isolation
-
-Subagents are isolated. A subagent doesn't inherit its parent's tools, skills, workspace, memory, processors, or subagents. Each child is a self-contained agent with its own directory.
-
-If multiple agents should share the same dependency, define it in code and assign it through each agent's config.
-
-## Nesting
-
-Subagents can declare their own `subagents/` directories, nesting up to three levels below the top-level agent. A `subagents/` directory nested deeper is ignored with a warning.
-
-```text
-src/mastra/agents/
-└── supervisor/            # depth 0
-    └── subagents/
-        └── researcher/    # depth 1
-            └── subagents/
-                └── summarizer/ # depth 2
-```
-
-## Naming rules
-
-- A subagent id that collides with one of the parent's tool keys is a build error.
-- A duplicate subagent id under the same parent is a build error.
-- If a subagent id also exists in the parent's `config.agents`, the `config.agents` entry wins and logs a warning.
-- If `config.agents` is a function, discovered subagents are ignored with a warning because they can't be statically merged.
-
-## Example
-
-This supervisor coordinates a research-and-writing flow. The `researcher` subagent owns search tools, while the `writer` subagent owns a workspace for drafting files.
-
-```text
-src/mastra/agents/
-└── research-supervisor/
-    ├── config.ts
-    ├── instructions.md
-    └── subagents/
-        ├── researcher/
-        │   ├── config.ts
-        │   ├── instructions.md
-        │   └── tools/
-        │       └── search_web.ts
-        └── writer/
-            ├── config.ts
-            ├── instructions.md
-            └── workspace/
-                └── draft-template.md
-```
-
-```typescript
-import { agentConfig } from '@mastra/core/agent'
-
-export default agentConfig({
-  model: 'openai/gpt-5.5',
-})
-```
-
-```markdown
-You coordinate research and writing.
-
-Delegate fact gathering to `researcher`. Delegate final drafting to `writer`.
-```
-
-```typescript
-import { agentConfig } from '@mastra/core/agent'
-
-export default agentConfig({
-  model: 'openai/gpt-5-mini',
-  description: 'Use to gather facts, sources, and concise research notes for a topic.',
-})
-```
-
-```typescript
-import { agentConfig } from '@mastra/core/agent'
-
-export default agentConfig({
-  model: 'openai/gpt-5.5',
-  description: 'Use to turn research notes into a structured draft.',
-})
-```

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

@@ -1,63 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Tools
-
-A file-based agent discovers tools from `.ts` and `.js` files directly under its `tools/` directory. Each discovered file is imported at build time, the file must default-export a [`createTool()`](https://mastra.ai/reference/tools/create-tool) result, and the filename without its extension becomes the tool key the model can call.
-
-Use this page for the file-based convention. For tool schemas, execution options, output shaping, and approval options, see the [`createTool()` reference](https://mastra.ai/reference/tools/create-tool).
-
-## Quickstart
-
-Place one tool per file under `tools/`. This file is exposed to the agent as `get_weather`.
-
-```typescript
-import { createTool } from '@mastra/core/tools'
-import { z } from 'zod'
-
-export default createTool({
-  id: 'get_weather',
-  description: 'Get the current weather for a city.',
-  inputSchema: z.object({
-    city: z.string(),
-  }),
-  outputSchema: z.object({
-    city: z.string(),
-    tempC: z.number(),
-  }),
-  execute: async ({ context }) => {
-    return { city: context.city, tempC: 21 }
-  },
-})
-```
-
-## Organizing tools
-
-Use one file per tool. Name the file after the action the model should take:
-
-- Use `get_weather.ts`, `search_docs.ts`, or `create_ticket.ts`.
-- Avoid vague names like `helper.ts`, `api.ts`, or `utils.ts`.
-- Co-locate tests next to the tool as `*.test.ts` or `*.spec.ts`; discovery ignores those files.
-- Keep shared helper code outside `tools/` or in files that don't match the discovered extensions under `tools/`.
-
-Because nested directories aren't discovered as tools, group related tools with clear filename prefixes instead of subfolders, such as `calendar_create_event.ts` and `calendar_list_events.ts`.
-
-## Tool options
-
-The file-based convention only controls where the tool lives and how it's registered. The tool API still comes from `createTool()`:
-
-- Use `description` to tell the model when to call the tool.
-- Use `inputSchema` and `outputSchema` for structured inputs and outputs.
-- Use `toModelOutput` when the model should see a different shape than the raw value returned from `execute`.
-- Use `requireApproval` when a tool needs human confirmation before execution.
-
-See the [`createTool()` reference](https://mastra.ai/reference/tools/create-tool) for all options and [tool approval](https://mastra.ai/docs/agent-controller/tool-approvals) for the approval flow.
-
-## Runtime boundary
-
-Tool code runs in your app/server runtime when the agent calls the tool. If a tool needs filesystem or shell isolation, call [workspace](https://mastra.ai/reference/file-based-agents/workspace) or sandbox APIs explicitly.
-
-## Precedence with config
-
-Discovered tools merge with any `tools` in [`config.ts`](https://mastra.ai/reference/file-based-agents/config). On a key collision, `config.tools` wins and a warning is logged.
-
-If `config.tools` is a function, discovered tools are ignored with a warning because function-valued tools can't be statically merged.

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

@@ -1,52 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Workflows
-
-Mastra discovers project-level workflows from `.ts` and `.js` files under `src/mastra/workflows/`. This convention isn't scoped to one agent: every file with a default export becomes a registered workflow, and the filename becomes the workflow key.
-
-Use this page for the file-based convention. For steps, schemas, control flow, streaming, state, and workflow execution, see [Workflows overview](https://mastra.ai/docs/workflows/overview).
-
-## Quickstart
-
-Create a file under `src/mastra/workflows/`, build the workflow with [`createWorkflow()`](https://mastra.ai/reference/workflows/workflow), and default-export it.
-
-```typescript
-import { createStep, createWorkflow } from '@mastra/core/workflows'
-import { z } from 'zod'
-
-const collectInputs = createStep({
-  id: 'collect-inputs',
-  inputSchema: z.object({ topic: z.string() }),
-  outputSchema: z.object({ topic: z.string(), audience: z.string() }),
-  execute: async ({ inputData }) => ({
-    topic: inputData.topic,
-    audience: 'engineering',
-  }),
-})
-
-const writeSummary = createStep({
-  id: 'write-summary',
-  inputSchema: z.object({ topic: z.string(), audience: z.string() }),
-  outputSchema: z.object({ report: z.string() }),
-  execute: async ({ inputData }) => ({
-    report: `Daily report about ${inputData.topic} for ${inputData.audience}.`,
-  }),
-})
-
-const dailyReport = createWorkflow({
-  id: 'daily-report',
-  inputSchema: z.object({ topic: z.string() }),
-  outputSchema: z.object({ report: z.string() }),
-})
-  .then(collectInputs)
-  .then(writeSummary)
-  .commit()
-
-export default dailyReport
-```
-
-Mastra registers this workflow under the `daily-report` key.
-
-## Precedence with code
-
-File-based workflows merge with workflows registered in [`new Mastra()`](https://mastra.ai/reference/core/mastra-class). On a key collision, the code-registered workflow wins.