@mastra/mcp-docs-server 1.2.14 → 1.2.15-alpha.10

package/.docs/reference/client-js/workflows.md

@@ -12,6 +12,19 @@ Retrieve a list of all available workflows:
 const workflows = await mastraClient.listWorkflows()
 ```
 
+## Getting workflow run counts
+
+Retrieve per-workflow counts of `running` and [`suspended`](https://mastra.ai/docs/workflows/suspend-and-resume) runs in a single request. The counts are computed on the server and keyed by the workflow's registry key — the key used when registering the workflow in the Mastra config, which can differ from the workflow's own `id`:
+
+```typescript
+const runCounts = await mastraClient.listWorkflowRunCounts()
+// { "cityWorkflow": { running: 2, suspended: 1 }, ... }
+```
+
+Returns: `Record<string, { running: number; suspended: number }>`
+
+The server may cache the counts for a few seconds between requests. Servers that predate this endpoint respond with `404 Not Found` — handle the error when the client can talk to older deployments.
+
 ## Working with a specific workflow
 
 Get an instance of a specific workflow by its ID:
@@ -212,28 +225,28 @@ A workflow run result yields the following:
 
 **payload** (`object`): Contains currentStep (id, status, output, payload) and workflowState (status, steps record)
 
-## Stored workflows
+## Dynamic workflows
 
-> **Beta:** Stored workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Dynamic workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.
 
-Stored workflows are workflow definitions expressed as JSON. The server persists each definition and registers it as a runnable workflow. See [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows) for the definition format.
+Dynamic workflows are workflow definitions expressed as JSON. The server persists each definition and registers it as a runnable workflow. See [Dynamic workflows](https://mastra.ai/docs/workflows/dynamic-workflows) for the definition format.
 
-### `listStoredWorkflows()`
+### `listDynamicWorkflows()`
 
-List stored workflow definitions, optionally filtered by `status` (`'active' | 'archived'`) and `authorId`:
+List dynamic workflow definitions, optionally filtered by `status` (`'active' | 'archived'`) and `authorId`:
 
 ```typescript
-const { definitions, total } = await mastraClient.listStoredWorkflows({
+const { definitions, total } = await mastraClient.listDynamicWorkflows({
   status: 'active',
 })
 ```
 
-### `upsertStoredWorkflow()`
+### `upsertDynamicWorkflow()`
 
-Create or replace a stored workflow definition. The server validates the definition, persists it, and live-registers it for execution:
+Create or replace a dynamic workflow definition. The server validates the definition, persists it, and live-registers it for execution:
 
 ```typescript
-const stored = await mastraClient.upsertStoredWorkflow({
+const stored = await mastraClient.upsertDynamicWorkflow({
   id: 'greeting-workflow',
   description: 'Returns a greeting for the supplied name',
   inputSchema: {
@@ -261,7 +274,7 @@ const stored = await mastraClient.upsertStoredWorkflow({
 When the root definition nests helper workflows that don't exist yet, pass them in the same request through `dependencies`. The server validates and registers the bundle as a unit and echoes the helper ids back as `dependencyIds`:
 
 ```typescript
-const stored = await mastraClient.upsertStoredWorkflow({
+const stored = await mastraClient.upsertDynamicWorkflow({
   id: 'root-workflow',
   // ...schemas and graph referencing 'helper-workflow'...
   dependencies: [helperDefinition],
@@ -270,33 +283,33 @@ const stored = await mastraClient.upsertStoredWorkflow({
 console.log(stored.dependencyIds) // ['helper-workflow']
 ```
 
-### `getStoredWorkflow()`
+### `getDynamicWorkflow()`
 
-Get a stored workflow instance for definition management. To execute a stored workflow, use `getWorkflow(id).createRun()` like any other workflow:
+Get a dynamic workflow instance for definition management. To execute a dynamic workflow, use `getWorkflow(id).createRun()` like any other workflow:
 
 ```typescript
-const storedWorkflow = mastraClient.getStoredWorkflow('greeting-workflow')
+const dynamicWorkflow = mastraClient.getDynamicWorkflow('greeting-workflow')
 ```
 
-### `storedWorkflow.details()`
+### `dynamicWorkflow.details()`
 
 Retrieve the persisted definition, including schemas, graph, status, and timestamps:
 
 ```typescript
-const definition = await storedWorkflow.details()
+const definition = await dynamicWorkflow.details()
 ```
 
-### `storedWorkflow.delete()`
+### `dynamicWorkflow.delete()`
 
 Delete the stored definition and unregister the live workflow:
 
 ```typescript
-await storedWorkflow.delete()
+await dynamicWorkflow.delete()
 ```
 
-### Executing a stored workflow
+### Executing a dynamic workflow
 
-Once registered, a stored workflow runs through the ordinary workflow API:
+Once registered, a dynamic workflow runs through the ordinary workflow API:
 
 ```typescript
 const workflow = mastraClient.getWorkflow('greeting-workflow')

package/.docs/reference/configuration.md

@@ -438,7 +438,7 @@ export const mastra = new Mastra({
 
 **Type:** `Record<string, MastraVector>`
 
-Vector stores for semantic search and embeddings. Used in RAG pipelines, similarity search, and other embedding-based features. Mastra supports multiple vector databases including Pinecone, PostgreSQL with pgvector, MongoDB, and more.
+Vector stores for semantic search and embeddings. Used in RAG pipelines, similarity search, and other embedding-based features. Mastra supports multiple vector databases including Pinecone, PostgreSQL with pgvector, OracleDB, MongoDB, and more.
 
 Visit the [RAG documentation](https://mastra.ai/guides/rag/overview) to learn more.
 
@@ -500,6 +500,31 @@ const mastra = new Mastra({
 
 ## Bundler options
 
+### bundler.entries
+
+**Type:** `Record<string, string>`\
+**Default:** `{}`
+
+Additional process entries to emit alongside the server bundle, as a map of output name to source path relative to your Mastra directory. Each entry becomes its own `<name>.mjs` in `.mastra/output`.
+
+Use this for long-running processes that run beside your Mastra server rather than inside it, such as a [LiveKit voice worker](https://mastra.ai/guides/voice/realtime-voice). The entry shares the output directory, `package.json`, and installed dependencies with the server, so one `mastra build` produces one deployable artifact you can start with different commands.
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+export const mastra = new Mastra({
+  bundler: {
+    entries: { 'voice-worker': './voice-worker.ts' },
+  },
+})
+```
+
+This emits `.mastra/output/voice-worker.mjs` next to `.mastra/output/index.mjs`. Dependencies imported only by the extra entry are analyzed too, so they're installed into the output.
+
+Entry names can contain `/` to nest the output. They can't be `index`, which is the server bundle, `tools`, which is the tool aggregator, or start with `tools/`, which is reserved for tool bundles.
+
+> **Note:** `mastra build` applies the [`bundler.externals`](#bundlerexternals) default of `true` only when you set no bundler options at all. Once you set `entries`, set `externals` explicitly as well if your extra entry depends on packages that can't be bundled, such as native modules.
+
 ### bundler.externals
 
 **Type:** `boolean | string[]`\

package/.docs/reference/core/{addStoredWorkflow.md → addDynamicWorkflow.md}

@@ -1,17 +1,17 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Mastra.addStoredWorkflow()
+# Mastra.addDynamicWorkflow()
 
-> **Beta:** Stored workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Dynamic workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.
 
-The `.addStoredWorkflow()` method validates a stored workflow definition and registers it as a live workflow on the instance, persisting it through the `workflowDefinitions` storage domain. Once registered, the workflow runs like any other workflow via [`getWorkflow()`](https://mastra.ai/reference/core/getWorkflow).
+The `.addDynamicWorkflow()` method validates a dynamic workflow definition and registers it as a live workflow on the instance, persisting it through the `workflowDefinitions` storage domain. Once registered, the workflow runs like any other workflow via [`getWorkflow()`](https://mastra.ai/reference/core/getWorkflow).
 
-See [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows) for a complete setup example and the [stored workflow definition reference](https://mastra.ai/reference/workflows/stored-workflow-definition) for the accepted fields and graph entries.
+See [Dynamic workflows](https://mastra.ai/docs/workflows/dynamic-workflows) for a complete setup example and the [dynamic workflow definition reference](https://mastra.ai/reference/workflows/dynamic-workflow-definition) for the accepted fields and graph entries.
 
 ## Usage example
 
 ```typescript
-await mastra.addStoredWorkflow({
+await mastra.addDynamicWorkflow({
   id: 'greeting-workflow',
   description: 'Returns a greeting for the supplied name',
   inputSchema: {
@@ -41,7 +41,7 @@ const result = await run.start({ inputData: { name: 'Ada' } })
 
 ## Parameters
 
-**def** (`StoredWorkflowGraph`): The workflow definition: id, optional description and metadata, JSON Schema input/output schemas, optional state and request-context schemas, and the step graph.
+**def** (`DynamicWorkflowGraph`): The workflow definition: id, optional description and metadata, JSON Schema input/output schemas, optional state and request-context schemas, and the step graph.
 
 ## Returns
 
@@ -52,11 +52,11 @@ A promise that resolves once the definition is validated, registered, and persis
 - The definition is fully validated (structure, references, schema flow) before anything is mutated. Agents, tools, and workflows referenced by the graph must already be registered on the instance.
 - Adding a definition with an existing ID replaces both the stored definition and the live registration. In-flight runs keep the graph they started with.
 - Without a storage adapter that supports the `workflowDefinitions` domain, the workflow is still validated and registered in memory, but the definition is lost on restart.
-- To add a root workflow together with helper workflows it nests, use [`addStoredWorkflows()`](https://mastra.ai/reference/core/addStoredWorkflows).
+- To add a root workflow together with helper workflows it nests, use [`addDynamicWorkflows()`](https://mastra.ai/reference/core/addDynamicWorkflows).
 
 ## Related
 
-- [Mastra.addStoredWorkflows()](https://mastra.ai/reference/core/addStoredWorkflows): Add a dependency-ordered bundle of definitions
+- [Mastra.addDynamicWorkflows()](https://mastra.ai/reference/core/addDynamicWorkflows): Add a dependency-ordered bundle of definitions
 - [Mastra.getWorkflow()](https://mastra.ai/reference/core/getWorkflow): Retrieve a registered workflow
-- [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows): Set up and use stored workflows
-- [Stored workflow definition](https://mastra.ai/reference/workflows/stored-workflow-definition): Definition fields and graph entries
+- [Dynamic workflows](https://mastra.ai/docs/workflows/dynamic-workflows): Set up and use dynamic workflows
+- [Dynamic workflow definition](https://mastra.ai/reference/workflows/dynamic-workflow-definition): Definition fields and graph entries

package/.docs/reference/core/{addStoredWorkflows.md → addDynamicWorkflows.md}

@@ -1,19 +1,19 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Mastra.addStoredWorkflows()
+# Mastra.addDynamicWorkflows()
 
-> **Beta:** Stored workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Dynamic workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.
 
-The `.addStoredWorkflows()` method adds a bundle of stored workflow definitions that may reference each other. The typical case is a root workflow plus helper workflows it nests, where none of the definitions exist yet.
+The `.addDynamicWorkflows()` method adds a bundle of dynamic workflow definitions that may reference each other. The typical case is a root workflow plus helper workflows it nests, where none of the definitions exist yet.
 
 The whole bundle is validated up front. Members are then registered in dependency order, so a helper is always in place before the workflow that nests it.
 
-[`addStoredWorkflow()`](https://mastra.ai/reference/core/addStoredWorkflow) is the single-member case.
+[`addDynamicWorkflow()`](https://mastra.ai/reference/core/addDynamicWorkflow) is the single-member case.
 
 ## Usage example
 
 ```typescript
-await mastra.addStoredWorkflows([
+await mastra.addDynamicWorkflows([
   helperDefinition, // nested by the root — order in the array doesn't matter
   rootDefinition, // graph contains { type: 'workflow', workflowId: helperDefinition.id }
 ])
@@ -21,7 +21,7 @@ await mastra.addStoredWorkflows([
 
 ## Parameters
 
-**defs** (`readonly StoredWorkflowGraph[]`): The workflow definitions to add. Nested-workflow references may resolve against the live registries or against other members of the same bundle.
+**defs** (`readonly DynamicWorkflowGraph[]`): The workflow definitions to add. Nested-workflow references may resolve against the live registries or against other members of the same bundle.
 
 ## Returns
 
@@ -35,6 +35,6 @@ A promise that resolves once every member is validated, registered, and persiste
 
 ## Related
 
-- [Mastra.addStoredWorkflow()](https://mastra.ai/reference/core/addStoredWorkflow): Add a single definition
-- [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows): Set up and use stored workflows
-- [Stored workflow definition](https://mastra.ai/reference/workflows/stored-workflow-definition): Definition fields and graph entries
+- [Mastra.addDynamicWorkflow()](https://mastra.ai/reference/core/addDynamicWorkflow): Add a single definition
+- [Dynamic workflows](https://mastra.ai/docs/workflows/dynamic-workflows): Set up and use dynamic workflows
+- [Dynamic workflow definition](https://mastra.ai/reference/workflows/dynamic-workflow-definition): Definition fields and graph entries

package/.docs/reference/editor/tool-provider.md

@@ -83,7 +83,32 @@ Composio tools use uppercase slug format: `GITHUB_CREATE_ISSUE`, `SLACK_SEND_MES
 
 ### Authentication
 
-Connections use per-author scope by default. Set `defaultScope: 'caller-supplied'` to bucket authorization by the caller identity resolved from request context.
+Connections use per-author scope by default. Set `defaultScope: 'caller-supplied'` to bucket authorization by the caller identity resolved from `MASTRA_RESOURCE_ID_KEY` in request context. Ensure each authenticated request provides a stable, unique resource ID. When using `MastraAuthWorkos`, configure `mapUserToResourceId` to set this value from the authenticated user.
+
+### Connection management tools
+
+Composio provides tools for starting and monitoring authorization from an agent chat. When `allowedToolkits` is set, include `composio` to make these tools available:
+
+```typescript
+const editor = new MastraEditor({
+  toolProviders: {
+    composio: new ComposioToolProvider({
+      apiKey: process.env.COMPOSIO_API_KEY!,
+      allowedToolkits: ['composio', 'gmail'],
+      defaultScope: 'caller-supplied',
+    }),
+  },
+})
+```
+
+Add only the connection management tools that the agent needs:
+
+| Tool                            | Behavior                                                                     |
+| ------------------------------- | ---------------------------------------------------------------------------- |
+| `COMPOSIO_MANAGE_CONNECTIONS`   | Creates an authorization link in chat through a session owned by the caller. |
+| `COMPOSIO_WAIT_FOR_CONNECTIONS` | Waits for the caller to finish authorization before the agent continues.     |
+
+`COMPOSIO_WAIT_FOR_CONNECTIONS` is optional. Without it, complete authorization and return to the chat. Then ask the agent to continue. The connected account remains associated with the caller resource ID for later requests.
 
 ***
 

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

@@ -69,32 +69,33 @@ Please note:
 
 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                  |
+| Setting      | File or folder                                                                                       | Why it lives there                                                         |
+| ------------ | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Instructions | [`instructions.md` or `instructions.ts`](https://mastra.ai/reference/file-based-agents/instructions) | Keeps the always-on prompt readable as markdown, or computed in TypeScript |
+| 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.
+| Domain       | Source A                                                                        | Source B                                                                                             | Winner                                                  |
+| ------------ | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| Instructions | Dynamic `config.instructions`                                                   | [`instructions.ts` or `instructions.md`](https://mastra.ai/reference/file-based-agents/instructions) | Dynamic `config.instructions`                           |
+| Instructions | Static `config.instructions`                                                    | [`instructions.ts` or `instructions.md`](https://mastra.ai/reference/file-based-agents/instructions) | The instructions file                                   |
+| Instructions | [`instructions.ts`](https://mastra.ai/reference/file-based-agents/instructions) | [`instructions.md`](https://mastra.ai/reference/file-based-agents/instructions)                      | `instructions.ts`                                       |
+| 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 `instructions.md`, `instructions.ts`, and `config.instructions` fails the build. Missing both `config.memory` and `memory.ts` leaves the agent without memory.
 
 ## Discovery lifecycle
 

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

@@ -2,9 +2,11 @@
 
 # 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.
+An agent's instructions hold its always-on system prompt: the model reads it on every turn. Use them 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.
+Write them in one of two files at the agent root. Use `instructions.md` when the prompt is fixed text. Use `instructions.ts` when the prompt needs code, for example when it's built from shared constants or resolved per request.
+
+Instructions are always in context, so keep them for stable behavior that applies to every request. Move anything conditional, large, or action-oriented 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
 
@@ -25,30 +27,53 @@ Effective instructions cover the parts of an agent's behavior that don't change
 
 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
+## Instructions in TypeScript
+
+Use `instructions.ts` when markdown can't express the prompt. The file default-exports a string, a system message, or a function returning one, and `agentInstructions()` types the export without changing it.
+
+Export a string when the prompt is assembled in code, for example from constants shared with the rest of your app:
+
+```typescript
+import { agentInstructions } from '@mastra/core/agent'
+import { SUPPORTED_UNITS } from '../../constants'
+
+export default agentInstructions(`
+You are a helpful weather assistant.
+Report conditions using one of these units: ${SUPPORTED_UNITS.join(', ')}.
+`)
+```
 
-When the prompt needs to change per request, for example based on the current user or runtime context, set a runtime-defined `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.
+Export a function when the prompt depends on the request. Mastra calls it on every turn and passes the request context:
 
 ```typescript
-import { agentConfig } from '@mastra/core/agent'
-
-export default agentConfig({
-  model: 'openai/gpt-5.6-sol',
-  instructions: ({ runtimeContext }) => {
-    const tier = runtimeContext.get('tier') ?? 'standard'
-    return `You are a support agent. Treat this as a ${tier}-tier customer.`
-  },
+import { agentInstructions } from '@mastra/core/agent'
+
+export default agentInstructions(({ requestContext }) => {
+  const tier = requestContext.get('tier') ?? 'standard'
+  return `You are a support agent. Treat this as a ${tier}-tier customer.`
 })
 ```
 
+The function can be `async` and receives `mastra` alongside `requestContext`, so it can read from storage or another registered primitive before returning the prompt.
+
+Both files can also live in a [subagent](https://mastra.ai/reference/file-based-agents/subagents) directory, which follows the same rules.
+
 ## 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.
+`instructions.md` and `instructions.ts` reach the deployed agent differently:
+
+- `instructions.md`: Mastra reads the file and inlines its contents into the generated code at build time.
+- `instructions.ts`: The generated code imports the module, so it's bundled like any other TypeScript file and can import from the rest of your project.
+
+Under `mastra dev`, editing either file triggers a rebuild. In a deployed app neither file is read from disk at runtime, so changes take effect 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):
+Instructions can come from `instructions.ts`, `instructions.md`, or the `instructions` field in [`config.ts`](https://mastra.ai/reference/file-based-agents/config):
+
+- A runtime-defined (function) `instructions` in `config.ts` wins over both files.
+- Otherwise `instructions.ts` wins over `instructions.md`.
+- `instructions.md` wins over a static `instructions` string in `config.ts`.
+- If none is present, the build fails and names the agent directory.
 
-- A runtime-defined (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.
+Defining instructions in more than one place logs a warning that names both sources and which one wins. Keep one source per agent.