@mastra/mcp-docs-server 1.2.15-alpha.1 → 1.2.15-alpha.11

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.

package/.docs/reference/index.md

@@ -82,9 +82,9 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [createCodingAgent()](https://mastra.ai/reference/coding-agent/create-coding-agent)
 - [Mastra Class](https://mastra.ai/reference/core/mastra-class)
 - [MastraModelGateway](https://mastra.ai/reference/core/mastra-model-gateway)
+- [.addDynamicWorkflow()](https://mastra.ai/reference/core/addDynamicWorkflow)
+- [.addDynamicWorkflows()](https://mastra.ai/reference/core/addDynamicWorkflows)
 - [.addGateway()](https://mastra.ai/reference/core/addGateway)
-- [.addStoredWorkflow()](https://mastra.ai/reference/core/addStoredWorkflow)
-- [.addStoredWorkflows()](https://mastra.ai/reference/core/addStoredWorkflows)
 - [.getAgent()](https://mastra.ai/reference/core/getAgent)
 - [.getAgentById()](https://mastra.ai/reference/core/getAgentById)
 - [.getDeployer()](https://mastra.ai/reference/core/getDeployer)
@@ -285,6 +285,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [libSQL Storage](https://mastra.ai/reference/storage/libsql)
 - [MongoDB Storage](https://mastra.ai/reference/storage/mongodb)
 - [MSSQL Storage](https://mastra.ai/reference/storage/mssql)
+- [OracleDB Storage](https://mastra.ai/reference/storage/oracledb)
 - [PostgreSQL Storage](https://mastra.ai/reference/storage/postgresql)
 - [Redis Storage](https://mastra.ai/reference/storage/redis)
 - [Retention (prune)](https://mastra.ai/reference/storage/retention)
@@ -302,6 +303,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Overview](https://mastra.ai/reference/templates/overview)
 - [askUserTool](https://mastra.ai/reference/tools/ask-user-tool)
 - [Bright Data Tools](https://mastra.ai/reference/tools/brightdata)
+- [createBedrockKBTool()](https://mastra.ai/reference/tools/bedrock-kb-tool)
 - [createCodeMode()](https://mastra.ai/reference/tools/create-code-mode)
 - [createDocumentChunkerTool()](https://mastra.ai/reference/tools/document-chunker-tool)
 - [createGraphRAGTool()](https://mastra.ai/reference/tools/graph-rag-tool)
@@ -326,6 +328,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [libSQL Vector Store](https://mastra.ai/reference/vectors/libsql)
 - [MongoDB Vector Store](https://mastra.ai/reference/vectors/mongodb)
 - [OpenSearch Vector Store](https://mastra.ai/reference/vectors/opensearch)
+- [OracleDB Vector Store](https://mastra.ai/reference/vectors/oracledb)
 - [PG Vector Store](https://mastra.ai/reference/vectors/pg)
 - [Pinecone Vector Store](https://mastra.ai/reference/vectors/pinecone)
 - [Qdrant Vector Store](https://mastra.ai/reference/vectors/qdrant)
@@ -365,9 +368,9 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.speak()](https://mastra.ai/reference/voice/voice.speak)
 - [.updateConfig()](https://mastra.ai/reference/voice/voice.updateConfig)
 - [Overview](https://mastra.ai/reference/workers/overview)
+- [Dynamic Workflow Definition](https://mastra.ai/reference/workflows/dynamic-workflow-definition)
 - [Run Class](https://mastra.ai/reference/workflows/run)
 - [Step Class](https://mastra.ai/reference/workflows/step)
-- [Stored Workflow Definition](https://mastra.ai/reference/workflows/stored-workflow-definition)
 - [Workflow Class](https://mastra.ai/reference/workflows/workflow)
 - [Workflow State Reader](https://mastra.ai/reference/workflows/workflow-state-reader)
 - [.agent()](https://mastra.ai/reference/workflows/workflow-methods/agent)

package/.docs/reference/observability/metrics/automatic-metrics.md

@@ -64,17 +64,19 @@ The detailed breakdown metrics (everything except `total_input` and `total_outpu
 
 ### When cost context is attached
 
-Cost context is attached to token metrics when the embedded pricing registry has a matching entry for the provider and model. Mastra includes the registry and covers common providers and models. If no match is found, token metrics are still emitted but without cost fields.
+Cost context is attached to token metrics when the provider reports a valid cost for every completed model step or when the embedded pricing registry has a matching entry for the provider and model. Mastra sums the per-step provider costs into one query total. If any completed step lacks a valid reported cost, Mastra uses the pricing registry instead of reporting a partial total. If neither source is available, token metrics are still emitted without cost fields.
+
+A caller-supplied `costContext` takes precedence over provider-reported costs and pricing registry estimates. Provider-reported totals use `costMetadata.source: 'provider_reported'`, `costMetadata.scope: 'query_total'`, and `costMetadata.reportedStepCount` to identify the source, scope, and number of completed steps included in the total.
 
 ### What cost fields may be included
 
-| Field           | Description                                                                  |
-| --------------- | ---------------------------------------------------------------------------- |
-| `provider`      | Provider name (e.g. `openai`, `anthropic`)                                   |
-| `model`         | Model identifier (e.g. `gpt-4o`, `claude-sonnet-4-20250514`)                 |
-| `estimatedCost` | Estimated cost for this metric, calculated from token count and pricing tier |
-| `costUnit`      | Currency unit (e.g. `USD`)                                                   |
-| `costMetadata`  | Additional pricing context (tier information, error details)                 |
+| Field           | Description                                                                                                        |
+| --------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `provider`      | Provider name (e.g. `openai`, `anthropic`)                                                                         |
+| `model`         | Model identifier (e.g. `gpt-4o`, `claude-sonnet-4-20250514`)                                                       |
+| `estimatedCost` | Estimated cost from token count and pricing tier, or a total reported by the provider                              |
+| `costUnit`      | Currency unit (e.g. `USD`)                                                                                         |
+| `costMetadata`  | Additional pricing context, including tier information, error details, and provider-reported cost source and scope |
 
 ## Correlation with traces
 

package/.docs/reference/rag/metadata-filters.md

@@ -2,7 +2,7 @@
 
 # Metadata filters
 
-Mastra provides a unified metadata filtering syntax across all vector stores, based on MongoDB/Sift query syntax. Each vector store translates these filters into their native format.
+Mastra provides a unified metadata filtering syntax across all vector stores, based on MongoDB/Sift query syntax. Each vector store translates these filters into its native query format. For example, PgVector uses PostgreSQL JSONB predicates, while OracleDB stores metadata as Oracle JSON and compiles filters to `JSON_VALUE`, `JSON_EXISTS`, `REGEXP_LIKE`, and `LIKE` predicates with bound values.
 
 ## Basic example
 
@@ -34,11 +34,11 @@ const results = await store.query({
 
 ### Array Operators
 
-`$in`Matches any value in array{ category: { $in: \["A", "B"] } }Supported by: All except Couchbase`$nin`Matches none of the values{ status: { $nin: \["deleted", "archived"] } }Supported by: All except Couchbase`$all`Matches arrays containing all elements{ tags: { $all: \["urgent", "high"] } }Supported by: Astra, Pinecone, Upstash, MongoDB`$elemMatch`Matches array elements meeting criteria{ scores: { $elemMatch: { $gt: 80 } } }Supported by: libSQL, PgVector, MongoDB
+`$in`Matches any value in array{ category: { $in: \["A", "B"] } }Supported by: All except Couchbase`$nin`Matches none of the values{ status: { $nin: \["deleted", "archived"] } }Supported by: All except Couchbase`$all`Matches arrays containing all elements{ tags: { $all: \["urgent", "high"] } }Supported by: Astra, Pinecone, Upstash, MongoDB, OracleDB`$elemMatch`Matches array elements meeting criteria{ scores: { $elemMatch: { $gt: 80 } } }Supported by: libSQL, PgVector, MongoDB, OracleDB
 
 ### Logical Operators
 
-`$and`Logical AND{ $and: \[{ price: { $gt: 100 } }, { stock: { $gt: 0 } }] }Supported by: All except Vectorize, Couchbase`$or`Logical OR{ $or: \[{ status: "active" }, { priority: "high" }] }Supported by: All except Vectorize, Couchbase`$not`Logical NOT{ price: { $not: { $lt: 100 } } }Supported by: Astra, Qdrant, Upstash, PgVector, libSQL, MongoDB`$nor`Logical NOR{ $nor: \[{ status: "deleted" }, { archived: true }] }Supported by: Qdrant, Upstash, PgVector, libSQL, MongoDB
+`$and`Logical AND{ $and: \[{ price: { $gt: 100 } }, { stock: { $gt: 0 } }] }Supported by: All except Vectorize, Couchbase`$or`Logical OR{ $or: \[{ status: "active" }, { priority: "high" }] }Supported by: All except Vectorize, Couchbase`$not`Logical NOT{ price: { $not: { $lt: 100 } } }Supported by: Astra, Qdrant, Upstash, PgVector, libSQL, MongoDB, OracleDB`$nor`Logical NOR{ $nor: \[{ status: "deleted" }, { archived: true }] }Supported by: Qdrant, Upstash, PgVector, libSQL, MongoDB, OracleDB
 
 ### Element Operators
 
@@ -46,7 +46,7 @@ const results = await store.query({
 
 ### Custom Operators
 
-`$contains`Text contains substring{ description: { $contains: "sale" } }Supported by: Upstash, libSQL, PgVector`$regex`Regular expression match{ name: { $regex: "^test" } }Supported by: Qdrant, PgVector, Upstash, MongoDB`$size`Array length check{ tags: { $size: { $gt: 2 } } }Supported by: Astra, libSQL, PgVector, MongoDB`$geo`Geospatial query{ location: { $geo: { type: "radius", ... } } }Supported by: Qdrant`$datetime`Datetime range query{ created: { $datetime: { range: { gt: "2024-01-01" } } } }Supported by: Qdrant`$hasId`Vector ID existence check{ $hasId: \["id1", "id2"] }Supported by: Qdrant`$hasVector`Vector existence check{ $hasVector: true }Supported by: Qdrant
+`$contains`Text contains substring{ description: { $contains: "sale" } }Supported by: Upstash, libSQL, PgVector, OracleDB`$regex`Regular expression match{ name: { $regex: "^test" } }Supported by: Qdrant, PgVector, Upstash, MongoDB, OracleDB`$size`Array length check{ tags: { $size: 3 } }Supported by: Astra, libSQL, PgVector, MongoDB, OracleDB`$geo`Geospatial query{ location: { $geo: { type: "radius", ... } } }Supported by: Qdrant`$datetime`Datetime range query{ created: { $datetime: { range: { gt: "2024-01-01" } } } }Supported by: Qdrant`$hasId`Vector ID existence check{ $hasId: \["id1", "id2"] }Supported by: Qdrant`$hasVector`Vector existence check{ $hasVector: true }Supported by: Qdrant
 
 ## Common rules and restrictions
 
@@ -124,6 +124,14 @@ const results = await store.query({
 - Empty arrays in conditions are handled gracefully
 - Metadata is stored in a JSONB column for efficient querying
 
+### OracleDB
+
+- Metadata is stored as Oracle JSON alongside each `VECTOR` row
+- Scalar comparisons use `JSON_VALUE`, while array, existence, and element-match checks use `JSON_EXISTS`
+- `$regex` uses Oracle `REGEXP_LIKE`; string `$contains` uses case-insensitive `LIKE`
+- Nested fields are supported with dot notation and are converted to quoted Oracle JSON paths
+- User-provided metadata values are bound as parameters instead of interpolated into SQL
+
 ### PgVector
 
 - Full support for PostgreSQL's native JSON querying capabilities
@@ -211,6 +219,7 @@ const results = await store.query({
 - [Cloudflare Vectorize](https://mastra.ai/reference/vectors/vectorize)
 - [libSQL](https://mastra.ai/reference/vectors/libsql)
 - [MongoDB](https://mastra.ai/reference/vectors/mongodb)
+- [OracleDB](https://mastra.ai/reference/vectors/oracledb)
 - [PgStore](https://mastra.ai/reference/vectors/pg)
 - [Pinecone](https://mastra.ai/reference/vectors/pinecone)
 - [Qdrant](https://mastra.ai/reference/vectors/qdrant)

package/.docs/reference/server/register-api-route.md

@@ -22,6 +22,8 @@ registerApiRoute("/items/:itemId", { ... })
 
 Custom route paths can't start with the server's configured `apiPrefix` (default: `/api`), as that prefix is reserved for built-in Mastra routes. If you set a custom `apiPrefix`, only that prefix is reserved. For example, with `apiPrefix: '/mastra/api'`, paths like `/api/my-endpoint` are allowed.
 
+> **Warning:** The default auth configuration protects `/api/*` and treats `/api`, `/api/auth/*` as public. When you change `apiPrefix`, those defaults no longer match and built-in routes fall outside the protected pattern. Update `server.auth.protected` and `server.auth.public` to reference the new prefix, and update any client code (including `MastraClient` `apiPrefix`) that hits `/api/*`.
+
 ### options
 
 **method** (`'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'ALL'`): HTTP method for the route

package/.docs/reference/server/routes.md

@@ -171,30 +171,44 @@ The route returns:
 
 ## Workflows
 
-| Method | Path                                      | Description                     |
-| ------ | ----------------------------------------- | ------------------------------- |
-| `GET`  | `/api/workflows`                          | List all workflows              |
-| `GET`  | `/api/workflows/:workflowId`              | Get workflow by ID              |
-| `POST` | `/api/workflows/:workflowId/create-run`   | Create a new workflow run       |
-| `POST` | `/api/workflows/:workflowId/start-async`  | Start workflow and await result |
-| `POST` | `/api/workflows/:workflowId/stream`       | Stream workflow execution       |
-| `POST` | `/api/workflows/:workflowId/resume`       | Resume suspended workflow       |
-| `POST` | `/api/workflows/:workflowId/resume-async` | Resume asynchronously           |
-| `GET`  | `/api/workflows/:workflowId/runs`         | List workflow runs              |
-| `GET`  | `/api/workflows/:workflowId/runs/:runId`  | Get specific run                |
-
-### Stored workflows
-
-Stored workflow definitions (beta) are workflows expressed as JSON, persisted through the `workflowDefinitions` storage domain, and live-registered on the running instance. See [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows).
-
-| Method   | Path                                      | Description                                                                    |
-| -------- | ----------------------------------------- | ------------------------------------------------------------------------------ |
-| `GET`    | `/api/stored/workflows`                   | List stored workflow definitions, filterable by `status` and `authorId`        |
-| `GET`    | `/api/stored/workflows/:storedWorkflowId` | Get a stored workflow definition by ID                                         |
-| `POST`   | `/api/stored/workflows`                   | Upsert a definition (plus optional helper `dependencies`) and live-register it |
-| `DELETE` | `/api/stored/workflows/:storedWorkflowId` | Delete a stored definition and unregister the live workflow                    |
-
-On authenticated servers, the read routes require the `stored-workflows:read` permission and the write routes require `stored-workflows:write`. Registered stored workflows are executed through the ordinary `/api/workflows/:workflowId` routes above.
+| Method | Path                                      | Description                                           |
+| ------ | ----------------------------------------- | ----------------------------------------------------- |
+| `GET`  | `/api/workflows`                          | List all workflows                                    |
+| `GET`  | `/api/workflows/run-counts`               | Get per-workflow counts of running and suspended runs |
+| `GET`  | `/api/workflows/:workflowId`              | Get workflow by ID                                    |
+| `POST` | `/api/workflows/:workflowId/create-run`   | Create a new workflow run                             |
+| `POST` | `/api/workflows/:workflowId/start-async`  | Start workflow and await result                       |
+| `POST` | `/api/workflows/:workflowId/stream`       | Stream workflow execution                             |
+| `POST` | `/api/workflows/:workflowId/resume`       | Resume suspended workflow                             |
+| `POST` | `/api/workflows/:workflowId/resume-async` | Resume asynchronously                                 |
+| `GET`  | `/api/workflows/:workflowId/runs`         | List workflow runs                                    |
+| `GET`  | `/api/workflows/:workflowId/runs/:runId`  | Get specific run                                      |
+
+### Run counts response
+
+The `/api/workflows/run-counts` endpoint returns counts of `running` and [`suspended`](https://mastra.ai/docs/workflows/suspend-and-resume) runs for every registered workflow. The record is keyed by the workflow's registry key from the Mastra config, and the server may cache the response for a few seconds:
+
+```typescript
+{
+  [workflowRegistryKey: string]: {
+    running: number;
+    suspended: number;
+  };
+}
+```
+
+### Dynamic workflows
+
+Dynamic workflow definitions (beta) are workflows expressed as JSON, persisted through the `workflowDefinitions` storage domain, and live-registered on the running instance. See [Dynamic workflows](https://mastra.ai/docs/workflows/dynamic-workflows).
+
+| Method   | Path                                       | Description                                                                    |
+| -------- | ------------------------------------------ | ------------------------------------------------------------------------------ |
+| `GET`    | `/api/stored/workflows`                    | List dynamic workflow definitions, filterable by `status` and `authorId`       |
+| `GET`    | `/api/stored/workflows/:dynamicWorkflowId` | Get a dynamic workflow definition by ID                                        |
+| `POST`   | `/api/stored/workflows`                    | Upsert a definition (plus optional helper `dependencies`) and live-register it |
+| `DELETE` | `/api/stored/workflows/:dynamicWorkflowId` | Delete a dynamic workflow definition and unregister the live workflow          |
+
+On authenticated servers, the read routes require the `stored-workflows:read` permission and the write routes require `stored-workflows:write`. Registered dynamic workflows are executed through the ordinary `/api/workflows/:workflowId` routes above.
 
 ### Create run request body
 

package/.docs/reference/storage/composite.md

@@ -251,6 +251,64 @@ const memoryStore = await storage.getStore('memory')
 const thread = await memoryStore?.getThreadById({ threadId: '...' })
 ```
 
+## Closing connections
+
+`close()` releases the connections of the stores a composite was built from: the `default` and `editor` stores, plus any domain that owns its own client. Each store is closed once, even when it backs several domains. When passed to the Mastra class, `close()` is called by `shutdown()`:
+
+```typescript
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { PostgresStore } from '@mastra/pg'
+import { Mastra } from '@mastra/core'
+
+const pgStore = new PostgresStore({
+  id: 'pg-storage',
+  connectionString: process.env.DATABASE_URL,
+})
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({ id: 'composite', default: pgStore }),
+})
+
+process.on('SIGTERM', async () => {
+  // Releases the Postgres pool, so the process can exit
+  await mastra.shutdown()
+})
+```
+
+A store you construct only to supply a domain isn't reachable through the composite. Keep a reference to it and close it yourself:
+
+```typescript
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { ClickhouseStore } from '@mastra/clickhouse'
+import { PostgresStore } from '@mastra/pg'
+import { Mastra } from '@mastra/core'
+
+const pgStore = new PostgresStore({
+  id: 'pg-storage',
+  connectionString: process.env.DATABASE_URL,
+})
+
+const clickhouseStore = new ClickhouseStore({
+  id: 'clickhouse-storage',
+  url: process.env.CLICKHOUSE_URL,
+  username: process.env.CLICKHOUSE_USERNAME,
+  password: process.env.CLICKHOUSE_PASSWORD,
+})
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: 'composite',
+    default: pgStore,
+    domains: { observability: clickhouseStore.stores?.observability },
+  }),
+})
+
+process.on('SIGTERM', async () => {
+  await mastra.shutdown()
+  await clickhouseStore.close()
+})
+```
+
 ## Use cases
 
 ### Separate databases for different workloads