@mastra/mcp-docs-server 1.1.45 → 1.1.46-alpha.0

package/.docs/docs/agents/code-mode.md

@@ -1,5 +1,7 @@
 # Code mode
 
+**Added in:** `@mastra/core@1.38.0`
+
 > **Alpha:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
 
 Code mode gives an agent a single tool that runs a short TypeScript program in a sandbox. Instead of calling tools one at a time, the model writes a program that orchestrates your existing tools as `external_*` functions, batching calls with `Promise.all`, aggregating with `reduce`, branching, and doing math in a real runtime, then returns a single result.

package/.docs/docs/agents/signal-providers.md

@@ -0,0 +1,222 @@
+# Signal providers
+
+**Added in:** `@mastra/core@1.39.0`
+
+> **Alpha:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
+
+A signal provider monitors an external source, such as GitHub, Slack, continuous integration (CI), or your own API, and pushes [notification signals](https://mastra.ai/docs/agents/signals) into subscribed agent threads.
+
+## When to use a signal provider
+
+Use a signal provider when an external system produces events that an agent should react to, and you want Mastra to manage the subscription bookkeeping for you.
+
+- The source emits events tied to a resource a thread cares about, such as a pull request, a channel, or a build.
+- You want one place that tracks which threads watch which external resources.
+- You want to receive events by polling, by webhook, or both.
+
+If you only need to push a one-off event into a thread, call [`agent.sendNotificationSignal()`](https://mastra.ai/reference/agents/agent) directly instead.
+
+## How signal providers work
+
+A signal provider is the producing side of the [signals](https://mastra.ai/docs/agents/signals) system. It brings external events into a thread, while the signal APIs control how the thread consumes them.
+
+A signal provider combines three capabilities:
+
+- **Subscription tracking:** The `SignalProvider` base class keeps an in-memory registry that maps each agent thread to the external resources it watches.
+- **Ingestion:** You override `poll()` for pull-based sources or `handleWebhook()` for push-based sources.
+- **Delivery:** When an event matches a subscription, call the protected `notify()` helper to forward a notification signal to the connected agent's thread.
+
+Register a provider by passing it to an agent. The agent connects the provider, starts polling if a `pollInterval` is set, and merges any processors or tools the provider exposes.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { CiSignals } from '../signals/ci-signals'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support Agent',
+  instructions: 'Help the user triage updates.',
+  model: 'openai/gpt-5.5',
+  signals: [new CiSignals()],
+})
+```
+
+> **Note:** Notification delivery requires a storage adapter with notification support, such as [libSQL](https://mastra.ai/reference/storage/libsql), [PostgreSQL](https://mastra.ai/reference/storage/postgresql), or [MongoDB](https://mastra.ai/reference/storage/mongodb). Configure storage on the Mastra instance so `notify()` can store notification records.
+
+## Quickstart
+
+The following example demonstrates a polling provider that watches CI pipelines and emits a notification when a subscribed pipeline fails.
+
+```typescript
+import { SignalProvider } from '@mastra/core/signals'
+import type { SignalProviderTarget, SignalSubscription } from '@mastra/core/signals'
+
+type BuildStatus = {
+  id: string
+  status: 'passed' | 'failed'
+}
+
+const builds = new Map<string, BuildStatus>([
+  ['acme-app-main', { id: 'build_123', status: 'failed' }],
+])
+
+async function fetchBuildStatus(pipeline: string): Promise<BuildStatus> {
+  return builds.get(pipeline) ?? { id: 'build_unknown', status: 'passed' }
+}
+
+export class CiSignals extends SignalProvider<'ci-signals'> {
+  readonly id = 'ci-signals' as const
+  readonly pollInterval = 30_000
+
+  watch(target: SignalProviderTarget, pipeline: string) {
+    return this.subscribe(target, pipeline)
+  }
+
+  unwatch(target: SignalProviderTarget, pipeline: string) {
+    return this.unsubscribe(target, pipeline)
+  }
+
+  async poll(subscriptions: SignalSubscription[]) {
+    for (const sub of subscriptions) {
+      const build = await fetchBuildStatus(sub.externalResourceId)
+      if (build.status !== 'failed') continue
+
+      await this.notify(
+        {
+          source: this.id,
+          kind: 'ci-status',
+          priority: 'high',
+          summary: `Build failed for ${sub.externalResourceId}`,
+          payload: build,
+          dedupeKey: `${this.id}:${sub.externalResourceId}:${build.id}`,
+        },
+        { resourceId: sub.resourceId, threadId: sub.threadId },
+      )
+    }
+  }
+}
+```
+
+Register the provider with an agent and subscribe a thread to the pipeline you want to watch.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { CiSignals } from '../signals/ci-signals'
+
+export const ciSignals = new CiSignals()
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support Agent',
+  instructions: 'Help the user triage CI updates.',
+  model: 'openai/gpt-5.5',
+  signals: [ciSignals],
+})
+
+ciSignals.watch({ resourceId: 'user_123', threadId: 'thread_456' }, 'acme-app-main')
+```
+
+Mastra calls `poll()` on the `pollInterval` with all active subscriptions. It skips a cycle when there are no subscriptions and doesn't overlap cycles, so a slow `poll()` doesn't run concurrently with itself.
+
+> **Note:** For a complete polling-provider build with notification storage, agent registration, thread subscription, and testing, follow [Building a signal provider](https://mastra.ai/guides/guide/signal-provider).
+
+## Polling and webhook providers
+
+Use polling when the external source doesn't push events to your app. Set `pollInterval` and override `poll(subscriptions)`. Each subscription includes the thread target and the external resource id to inspect.
+
+Use webhooks when the external source can call your app. Override `handleWebhook(request)`, parse the payload, find matching subscriptions, and call `notify()` for each match.
+
+```typescript
+import { SignalProvider } from '@mastra/core/signals'
+import type { SignalProviderWebhookRequest } from '@mastra/core/signals'
+
+export class CiSignals extends SignalProvider<'ci-signals'> {
+  readonly id = 'ci-signals' as const
+
+  async handleWebhook(request: SignalProviderWebhookRequest) {
+    const payload = request.body as { pipeline: string; status: string }
+    const subscriptions = this.getSubscriptionsForResource(payload.pipeline)
+
+    for (const sub of subscriptions) {
+      await this.notify(
+        {
+          source: this.id,
+          kind: 'ci-status',
+          priority: 'high',
+          summary: `Build ${payload.status} for ${payload.pipeline}`,
+          payload,
+        },
+        { resourceId: sub.resourceId, threadId: sub.threadId },
+      )
+    }
+
+    return { status: 200, body: { matched: subscriptions.length } }
+  }
+}
+```
+
+`handleWebhook()` is a provider method, not an auto-mounted HTTP route. Invoke it from your own endpoint, passing the request body, headers, and any route params.
+
+> **Note:** Visit [`SignalProvider` reference](https://mastra.ai/reference/signals/signal-provider) for subscription, polling, lifecycle, and `notify()` details. For the complete notification payload shape, including deduplication and coalescing fields, visit [`Agent.sendNotificationSignal()` reference](https://mastra.ai/reference/agents/agent).
+
+## Built-in webhook provider
+
+For generic webhook sources, use [`WebhookSignalProvider`](https://mastra.ai/reference/signals/webhook-signal-provider) instead of writing a subclass. Configure it with a function that extracts a resource id from the payload, and an optional function that builds the notification.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { WebhookSignalProvider } from '@mastra/core/signals'
+
+const webhooks = new WebhookSignalProvider({
+  extractResourceId: payload => (payload as { repository: string }).repository,
+  buildNotification: (payload, sub) => ({
+    source: 'ci',
+    kind: 'build-status',
+    priority: 'medium',
+    summary: `Build ${(payload as { status: string }).status} for ${sub.externalResourceId}`,
+  }),
+})
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support Agent',
+  instructions: 'Help the user triage updates.',
+  model: 'openai/gpt-5.5',
+  signals: [webhooks],
+})
+
+webhooks.subscribeThread({ resourceId: 'user_123', threadId: 'thread_456' }, 'acme/app')
+```
+
+When a webhook arrives, call `webhooks.handleWebhook({ body, headers })` from your route. The provider matches the extracted resource id against its subscriptions and notifies each matching thread.
+
+## Advanced provider capabilities
+
+A provider can support more than event ingestion. Add only the capabilities your source needs.
+
+- **Durable subscriptions:** The base registry is in-memory and per-process. Persist subscriptions yourself when they must survive a restart, then rehydrate them in [`start()`](https://mastra.ai/reference/signals/signal-provider).
+- **Lifecycle hooks:** Override [`start()`](https://mastra.ai/reference/signals/signal-provider) for async setup and [`stop()`](https://mastra.ai/reference/signals/signal-provider) for cleanup. Call `super.stop()` when overriding `stop()` so the base provider can stop polling and clear its registry.
+- **Processors and tools:** Return processors from [`getInputProcessors()`](https://mastra.ai/reference/signals/signal-provider) or [`getOutputProcessors()`](https://mastra.ai/reference/signals/signal-provider), and return agent-callable tools from [`getTools()`](https://mastra.ai/reference/signals/signal-provider).
+
+The `@mastra/github-signals` package is a production signal provider that watches GitHub pull requests and notifies threads about comments, review state, continuous integration status, and merges. Use it as a reference for polling, durable subscriptions, tools, processors, and lifecycle hooks.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { GithubSignals } from '@mastra/github-signals'
+
+export const devAgent = new Agent({
+  id: 'dev-agent',
+  name: 'Dev Agent',
+  instructions: 'Help triage pull request activity.',
+  model: 'openai/gpt-5.5',
+  signals: [new GithubSignals()],
+})
+```
+
+## Related
+
+- [Guide: Building a signal provider](https://mastra.ai/guides/guide/signal-provider)
+- [Signals](https://mastra.ai/docs/agents/signals)
+- [Notification signals](https://mastra.ai/docs/agents/signals)
+- [`SignalProvider` reference](https://mastra.ai/reference/signals/signal-provider)
+- [`WebhookSignalProvider` reference](https://mastra.ai/reference/signals/webhook-signal-provider)

package/.docs/docs/agents/signals.md

@@ -1,25 +1,41 @@
 # Signals
 
+**Added in:** `@mastra/core@1.39.0`
+
 > **Alpha:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
 
 Signals are a way to interact with an agent through a thread. Instead of starting every interaction with `agent.stream()`, subscribe to a thread and send messages or signals. Mastra either wakes the agent when the thread is idle, drops input into the running agent loop, or queues input for the next turn.
 
 Use message APIs for user-authored input. Use `sendSignal()` for lower-level system context, such as background task notifications, policy reminders, or processor-generated context.
 
+## When to use signals
+
+Use signals when an agent thread needs new input or context outside the original `stream()` call. Signals are useful when users send follow-up messages while a run is active, when background systems need to add context to a thread, or when external events should wake, update, or notify the agent.
+
+Use `sendMessage()` and `queueMessage()` for user-authored input. Use `sendSignal()` for lower-level system context. Use `sendStateSignal()` for durable state lanes, and use `sendNotificationSignal()` when an external event should create a durable notification inbox record.
+
 ## Quickstart
 
-Subscribe to the thread before sending messages. The subscription receives the active stream when the message wakes the agent or enters a running loop.
+Create an agent, subscribe to a thread, then send a message to that thread. The subscription receives the active stream when the message wakes the agent or enters a running loop.
 
 ```typescript
-const subscription = await agent.subscribeToThread({
-  resourceId: 'user_123',
-  threadId: 'thread_456',
+import { Agent } from '@mastra/core/agent'
+
+const agent = new Agent({
+  id: 'support-agent',
+  name: 'Support Agent',
+  instructions: 'Help the user compare options.',
+  model: 'openai/gpt-5.5',
 })
 
-agent.sendMessage('Compare that with the previous option.', {
+const thread = {
   resourceId: 'user_123',
   threadId: 'thread_456',
-})
+}
+
+const subscription = await agent.subscribeToThread(thread)
+
+await agent.sendMessage('Compare that with the previous option.', thread)
 
 for await (const chunk of subscription.stream) {
   console.log(chunk)
@@ -28,7 +44,9 @@ for await (const chunk of subscription.stream) {
 
 When the thread has a running agent stream, `sendMessage()` becomes new input inside that agent loop. When the thread is idle, Mastra starts a stream with the message as the first input.
 
-## Send a message now
+## Message input
+
+### Send a message now
 
 Use `sendMessage()` when the user expects the active agent to see the message immediately.
 
@@ -53,7 +71,7 @@ The model receives attributed messages as XML-wrapped user input:
 
 Messages without attributes are sent as plain user input.
 
-## Queue a message for the next turn
+### Queue a message for the next turn
 
 Use `queueMessage()` when a user sends a follow-up but the active model call should finish first. Mastra waits for the active run to complete, then starts a new run on the same thread.
 
@@ -66,7 +84,9 @@ agent.queueMessage('Also check whether the tests need updates.', {
 
 When the thread is idle, `queueMessage()` starts a run immediately. When the thread is active, it preserves turn order by starting a new run after the active run completes.
 
-## Control low-level signal behavior
+## Signal context
+
+### Control low-level signal behavior
 
 Use `sendSignal()` when you need to send system-generated context instead of user-authored input. For external events, use `type: 'notification'`. By default, Mastra delivers signals to active runs and wakes idle threads. Use `ifActive.behavior` and `ifIdle.behavior` to change that behavior.
 
@@ -88,31 +108,11 @@ const result = agent.sendSignal(
 await result.persisted
 ```
 
-The behavior options are:
+Pass `ifIdle.streamOptions` when the idle wake-up stream needs options such as model settings, tools, or runtime context.
 
-- `ifActive.behavior: 'deliver'`: Add the signal or message to the running agent loop. This is the default.
-- `ifActive.behavior: 'persist'`: Save the signal or message to memory without adding it to the running loop.
-- `ifActive.behavior: 'discard'`: Ignore the signal or message while the thread is active.
-- `ifIdle.behavior: 'wake'`: Start a stream with the signal or message as the first input. This is the default.
-- `ifIdle.behavior: 'persist'`: Save the signal or message to memory without starting a stream.
-- `ifIdle.behavior: 'discard'`: Ignore the signal or message while the thread is idle.
-
-Pass `ifIdle.streamOptions` when the idle wake-up stream needs options such as model settings, tools, or runtime context. You don't need to repeat `memory.resource` or `memory.thread`; Mastra uses the top-level `resourceId` and `threadId` for the thread.
-
-```typescript
-agent.sendMessage('Continue with the next step.', {
-  resourceId: 'user_123',
-  threadId: 'thread_456',
-  ifIdle: {
-    behavior: 'wake',
-    streamOptions: {
-      maxSteps: 3,
-    },
-  },
-})
-```
+> **Note:** Visit [`Agent.sendSignal()` reference](https://mastra.ai/reference/agents/agent) for `ifActive`, `ifIdle`, branch attributes, and `streamOptions`.
 
-## Send notification context
+### Send notification context
 
 Signals have a semantic `type` and an LLM-facing `tagName`. Use `type` to describe the signal category. Use `tagName` to control the XML tag the model sees.
 
@@ -143,11 +143,11 @@ The model receives the signal as context like this:
 
 Use XML-safe `tagName` and attribute names. They can contain letters, numbers, underscores, periods, and hyphens. They must start with a letter or underscore.
 
-### Storage support
+#### Storage support
 
 Notification inbox storage is available in the storage adapters that support richer memory and signal workflows: [libSQL](https://mastra.ai/reference/storage/libsql), [PostgreSQL](https://mastra.ai/reference/storage/postgresql), and [MongoDB](https://mastra.ai/reference/storage/mongodb). These adapters expose notification records through `getStore('notifications')`.
 
-## Send processor context
+### Send processor context
 
 Processors can send reactive signals during a run. A processor should inspect the chat history, react to a specific trigger, and avoid sending the same context more than once.
 
@@ -193,50 +193,19 @@ Reactive signals default to `tagName: 'system-reminder'`, so the model receives
 
 Awaiting `sendSignal()` preserves stream echo ordering when a subscribed thread is active.
 
-## Conditional attributes
-
-Use `ifActive.attributes` and `ifIdle.attributes` to tag input with context that depends on whether the agent is active or idle at delivery time. Mastra resolves the correct branch when the input is accepted.
-
-```typescript
-agent.sendMessage(
-  {
-    contents: 'Also cover the edge cases.',
-    attributes: { source: 'chat' },
-  },
-  {
-    resourceId: 'user_123',
-    threadId: 'thread_456',
-    ifActive: { attributes: { delivery: 'while-active' } },
-    ifIdle: { attributes: { delivery: 'new-message' } },
-  },
-)
-```
-
-When the agent is working, the model sees:
+### Conditional attributes
 
-```xml
-<user source="chat" delivery="while-active">Also cover the edge cases.</user>
-```
-
-When the agent is idle:
+Use `ifActive.attributes` and `ifIdle.attributes` to tag input with context that depends on whether the agent is active or idle at delivery time. Top-level `attributes` always apply, and Mastra merges the selected branch's `attributes` into them when the input is accepted.
 
-```xml
-<user source="chat" delivery="new-message">Also cover the edge cases.</user>
-```
+> **Note:** Visit [`Agent.sendMessage()` reference](https://mastra.ai/reference/agents/agent) and [`Agent.sendSignal()` reference](https://mastra.ai/reference/agents/agent) for branch-specific attributes.
 
-Top-level `attributes` always apply. The selected branch's `attributes` are merged into them at delivery time. The `delivery` name shown above isn't a special Mastra API field. It's a custom attribute name used for this example. Add any attribute names that suit your use case.
+## State and notification signals
 
-## State signals
+### State signals
 
 State signals expose named, thread-scoped context lanes. Use them for durable context that changes over time, such as browser state, editor state, or a background watcher result.
 
-Each state signal needs:
-
-- `id`: The state lane name, such as `browser`.
-- `cacheKey`: A producer-owned key for deduping the current state.
-- `mode`: `snapshot` for an authoritative state copy, or `delta` for a change event.
-
-Use `sendStateSignal()` when an external producer detects a state change.
+Use `sendStateSignal()` when an external producer detects a state change. Each state signal identifies a state lane, a producer-owned cache key, and whether the update is a snapshot or delta.
 
 ```typescript
 await agent.sendStateSignal(
@@ -258,16 +227,9 @@ await agent.sendStateSignal(
 )
 ```
 
-When Mastra accepts a state signal, it stores compact tracking metadata on the thread. The metadata records the lane's current `cacheKey`, current mode, version, last signal id, and last snapshot signal id. If a producer sends the same `cacheKey` and mode again while that state is still current, Mastra skips the duplicate.
-
-State signal fields have separate roles:
+When Mastra accepts a state signal, it stores compact tracking metadata on the thread. If a producer sends the same `cacheKey` and mode again while that state is still current, Mastra skips the duplicate.
 
-- `contents`: The representation the model reads.
-- `value`: The structured snapshot for `mode: 'snapshot'`.
-- `delta`: The structured change for `mode: 'delta'`.
-- `metadata.state`: The runtime tracking envelope with `id`, `mode`, `cacheKey`, `version`, and `threadId`.
-
-Use `computeStateSignal()` when a processor owns a state lane. Mastra calls it once per model input step after `processInputStep()`. If the processor omits `id`, Mastra uses the processor id as the state lane id. Set `stateId` when the public state lane should differ from the processor id.
+Use `computeStateSignal()` when a processor owns a state lane. Mastra calls it once per model input step after `processInputStep()`. Visit [`Agent.sendStateSignal()` reference](https://mastra.ai/reference/agents/agent) for state signal fields and return values.
 
 ```typescript
 import type { ComputeStateSignalArgs, Processor } from '@mastra/core/processors'
@@ -304,31 +266,15 @@ Mastra passes `lastSnapshot` and `deltasSinceSnapshot` into `computeStateSignal(
 
 The built-in browser context processor emits state under the `browser` id with snapshot and delta modes.
 
-## Notification signals
+### Notification signals
 
 Notification signals represent external events such as GitHub activity, email, Slack mentions, CI status, incidents, recordings, or direct messages. Use `agent.sendNotificationSignal()` when the event should create a durable inbox record.
 
-Notification delivery has two phases:
-
-- **Ingress**: `agent.sendNotificationSignal()` stores a notification record, then resolves the agent's delivery policy.
-- **Dispatch**: Mastra consumes due records stamped with `deliverAt` or `summaryAt` and emits full notification or summary signals.
-
-A notification record stores the source, kind, priority, summary, payload, resource id, thread id, agent id, coalescing keys, and delivery metadata. The delivery decision controls what happens after ingress:
+Notification delivery has two phases. During ingress, `agent.sendNotificationSignal()` stores a notification record and resolves the agent's delivery policy. During dispatch, Mastra consumes due records and emits full notification or summary signals.
 
-- `deliver` or `queue`: Emit a full `<notification>` signal and mark the record `delivered`.
-- `defer`: Keep the record `pending` with `deliverAt`.
-- `summarize`: Keep the record `pending` with `summaryAt`, or emit an immediate summary when the policy requests it.
-- `persist`: Keep the record `pending` in the inbox without scheduled delivery.
-- `discard`: Mark the record `discarded` and emit no signal.
+The default delivery policy is priority-aware. Urgent notifications deliver immediately, while lower-priority notifications may be batched into summaries or wait until the thread is idle.
 
-The default delivery policy is priority-aware:
-
-| Priority | Active thread                                                                                            | Idle thread                                                                                     |
-| -------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `urgent` | Deliver a full notification immediately                                                                  | Deliver a full notification immediately                                                         |
-| `high`   | Emit a summary immediately, keep `deliverAt`, then deliver the full notification when the thread is idle | Deliver a full notification immediately                                                         |
-| `medium` | Batch with `summaryAt` and later deliver one notification summary                                        | Deliver a full notification immediately                                                         |
-| `low`    | Batch with `summaryAt` and later deliver one notification summary                                        | Batch with `summaryAt` and later deliver one notification summary without waking the model loop |
+> **Note:** Visit [`Agent.sendNotificationSignal()` reference](https://mastra.ai/reference/agents/agent) for notification fields, [`Agent` constructor reference](https://mastra.ai/reference/agents/agent) for `notifications.deliveryPolicy` configuration, and [`createNotificationInboxTool()` reference](https://mastra.ai/reference/signals/create-notification-inbox-tool) for inbox tool actions.
 
 ```typescript
 await agent.sendNotificationSignal(
@@ -364,86 +310,21 @@ Notification summaries tell the model that inbox records are waiting:
 
 When Mastra emits a summary, it clears `summaryAt` and sets `summarySignalId` on each summarized record. The records stay pending and readable. When Mastra emits a full notification, it sets `deliveredSignalId` and marks the record `delivered`. If the inbox tool reads a notification first, it can inject the full notification signal and mark the record `seen`, which prevents duplicate full delivery.
 
-Configure a delivery policy on the agent when some notifications should wait for a different dispatch window or summary rollup.
+Configure a delivery policy on the agent when some notifications should wait for a different dispatch window or summary rollup. Enable scheduled dispatch at the Mastra level when deferred notifications and summary rollups should be delivered automatically.
 
-```typescript
-export const supportAgent = new Agent({
-  id: 'support-agent',
-  name: 'Support Agent',
-  instructions: 'Help the user triage updates.',
-  model: 'openai/gpt-5.5',
-  notifications: {
-    deliveryPolicy: {
-      priorities: {
-        urgent: 'deliver',
-      },
-      decide: ({ record }) => {
-        if (record.priority === 'low') {
-          return {
-            action: 'summarize',
-            summaryAt: new Date(Date.now() + 30 * 60 * 1000),
-          }
-        }
-      },
-    },
-  },
-})
-```
+> **Note:** Visit [`Agent` constructor reference](https://mastra.ai/reference/agents/agent) for `notifications.deliveryPolicy` and [`Mastra` class reference](https://mastra.ai/reference/core/mastra-class) for runtime notification dispatch configuration.
 
-Enable scheduled dispatch at the Mastra level so deferred notifications and summary rollups are delivered through the existing workflow scheduler.
+#### Notification inbox tool
 
-```typescript
-export const mastra = new Mastra({
-  agents: { supportAgent },
-  storage,
-  notifications: {
-    dispatch: {
-      enabled: true,
-      cron: '*/1 * * * *',
-      batchSize: 100,
-    },
-  },
-})
-```
+Use `createNotificationInboxTool()` to give agents one tool for inbox actions instead of many CRUD tools. Use `read` after a `<notification-summary>` signal when the agent needs the full records behind the summary. The notification contents are delivered as signals, not as normal tool output.
 
-`notifications.dispatch.enabled` registers an internal workflow with the default cron `*/1 * * * *`. The dispatcher reads due notification records from storage, groups summaries by `agentId`, `resourceId`, and `threadId`, and emits signals through the Agent thread runtime. It isn't a user-facing entrypoint.
+> **Note:** Visit [`createNotificationInboxTool()` reference](https://mastra.ai/reference/signals/create-notification-inbox-tool) for the setup example, input schema, and action behavior.
 
-### Notification inbox tool
+`sendNotificationSignal()` requires a storage domain with `notifications` support. Use `sendSignal({ type: 'notification' })` only for lower-level notification-shaped context that should bypass inbox storage.
 
-Use `createNotificationInboxTool()` to give agents one tool for inbox actions instead of many CRUD tools.
+## Compatibility and APIs
 
-```typescript
-import { createNotificationInboxTool } from '@mastra/core/notifications'
-
-const notificationsStorage = await storage.getStore('notifications')
-
-export const supportAgent = new Agent({
-  id: 'support-agent',
-  name: 'Support Agent',
-  instructions: 'Help the user triage updates.',
-  model: 'openai/gpt-5.5',
-  tools: {
-    notificationInbox: createNotificationInboxTool({ storage: notificationsStorage }),
-  },
-})
-```
-
-The tool id is `notification-inbox`. It supports these actions:
-
-- `list`: List notifications for the current thread.
-- `read`: Deliver readable full notification signals into the chat when possible, then mark records `seen`.
-- `markSeen`: Mark one record `seen`.
-- `dismiss`: Mark one record `dismissed`.
-- `archive`: Mark one record `archived`.
-- `search`: Search notification summaries in the current thread.
-
-The tool uses the current `threadId` from the tool execution context unless one is provided. Use `read` after a `<notification-summary>` signal when the agent needs the full records behind the summary. The `read` result reports how many notifications will be delivered; it doesn't use normal tool output as the main context channel for the notification contents.
-
-`sendNotificationSignal()` requires a storage domain with `notifications` support. LibSQL supports notifications. Other storage adapters need matching notification domain support before they can store notification records.
-
-Use `sendSignal({ type: 'notification' })` only for lower-level notification-shaped context that should bypass inbox storage.
-
-## Compatibility
+### Compatibility
 
 Mastra still accepts legacy signal payloads such as `type: 'user-message'` and `type: 'system-reminder'`. It normalizes them internally to the new category and tag shape:
 
@@ -454,26 +335,17 @@ Existing stored signal rows and older clients continue to load through the compa
 
 > **Note:** Visit [Agent signals reference](https://mastra.ai/reference/agents/agent) for the full message, signal, and subscription types.
 
-## Approve tool calls
-
-When a subscribed run pauses for tool approval, approve or decline the tool call with the subscription-native methods. The call returns a JSON acknowledgement. The resumed chunks arrive through the existing thread subscription.
+### Approve tool calls
 
-```typescript
-await agent.sendToolApproval({
-  resourceId: 'user_123',
-  threadId: 'thread_456',
-  toolCallId: 'tool-call_456',
-  approved: true,
-})
-```
+When a subscribed run pauses for tool approval, approve or decline the tool call with the subscription-native methods. The resumed chunks arrive through the existing thread subscription.
 
-Pass `approved: false` to decline the same pending tool call. Use the older `approveToolCall()` and `declineToolCall()` methods only when you are rendering the separate continuation stream directly.
+> **Note:** Visit [`client.getAgent().sendToolApproval()` reference](https://mastra.ai/reference/client-js/agents) and [server agent routes](https://mastra.ai/reference/server/routes) for request and response shapes.
 
-## Use HTTP routes
+### Use HTTP routes
 
 If you call Mastra over HTTP directly, use `POST /api/agents/:agentId/send-message` for immediate messages and `POST /api/agents/:agentId/queue-message` for next-turn messages. For subscription-native tool approval, use `POST /api/agents/:agentId/send-tool-approval`. See [Server routes reference](https://mastra.ai/reference/server/routes) for request and response schemas.
 
-## Use the client SDK
+### Use the client SDK
 
 The JavaScript client exposes thread signal APIs. Use `subscribeToThread()` before sending thread input so the client can render the stream that wakes from, or receives, the input.
 
@@ -499,9 +371,9 @@ await subscription.processDataStream({
 })
 ```
 
-Use `reconnect: true` for long-lived subscriptions. The client resubscribes when the stream closes or a reconnect request fails, such as after a proxy idle timeout or a dropped network connection.
+Use `reconnect: true` for long-lived subscriptions. Visit [`client.getAgent().subscribeToThread()` reference](https://mastra.ai/reference/client-js/agents) for reconnect options.
 
-## Keep custom SSE subscriptions alive
+### Keep custom SSE subscriptions alive
 
 If you expose your own Server-Sent Events (SSE) endpoint for thread subscriptions, send periodic heartbeat frames while the stream is idle. This keeps browsers, proxies, and load balancers from closing the connection before the next signal or model chunk arrives.
 
@@ -524,7 +396,9 @@ Use heartbeats together with client-side reconnect logic. Heartbeats reduce idle
 - [`Agent.sendMessage()`](https://mastra.ai/reference/agents/agent)
 - [`Agent.queueMessage()`](https://mastra.ai/reference/agents/agent)
 - [`Agent.sendSignal()`](https://mastra.ai/reference/agents/agent)
+- [`Agent.sendStateSignal()`](https://mastra.ai/reference/agents/agent)
 - [`Agent.subscribeToThread()`](https://mastra.ai/reference/agents/agent)
+- [`createNotificationInboxTool()`](https://mastra.ai/reference/signals/create-notification-inbox-tool)
 - [`client.getAgent().sendMessage()`](https://mastra.ai/reference/client-js/agents)
 - [`client.getAgent().queueMessage()`](https://mastra.ai/reference/client-js/agents)
 - [`client.getAgent().sendSignal()`](https://mastra.ai/reference/client-js/agents)

package/.docs/docs/getting-started/build-with-ai.md

@@ -89,9 +89,9 @@ Each `dist/docs` includes:
 
 ## Context files
 
-Mastra provides a root [`llms.txt`](https://mastra.ai/llms.txt) file that contains an overview of all available documentation pages.
+Mastra provides a root [`llms.txt`](https://mastra.ai/llms.txt) file that contains an overview of all available documentation pages. It doesn't provide an `llms-full.txt` file as it's not useful to have all documentation in one file.
 
-Each documentation page also has its own `llms.txt` file. These files are streamlined markdown files. At the end of each docs page you'll find a link to the corresponding `llms.txt` file.
+Instead, each documentation page has its own `llms.txt` file. These files are streamlined markdown files. At the end of each docs page you'll find a link to the corresponding `llms.txt` file.
 
 Add `/llms.txt` to any Mastra docs URL to access it. You can also request it by adding a `.md` extension to the end of the URL.
 

package/.docs/docs/mastra-platform/configuration.md

@@ -71,4 +71,4 @@ cp .mastra-project.production.json .mastra-project.json
 mastra studio deploy --env-file .env.production --yes
 ```
 
-Each project has its own Studio URL and can send observability data to the Mastra platform. When using [`MastraPlatformExporter`](https://mastra.ai/docs/observability/tracing/exporters/mastra-platform), set `MASTRA_PROJECT_ID` and `MASTRA_PLATFORM_ACCESS_TOKEN` per environment so traces route to the matching platform project.
+Each project has its own Studio URL and can send observability data to the Mastra platform. When using [`MastraPlatformExporter`](https://mastra.ai/docs/observability/integrations/exporters/mastra-platform), set `MASTRA_PROJECT_ID` and `MASTRA_PLATFORM_ACCESS_TOKEN` per environment so traces route to the matching platform project.

package/.docs/docs/mastra-platform/overview.md

@@ -32,4 +32,4 @@ Once you're ready to deploy your application to production, use [`mastra studio
 
 Follow the [Studio on Mastra platform](https://mastra.ai/docs/mastra-platform/studio) and [Server on Mastra platform](https://mastra.ai/docs/mastra-platform/server) docs for step-by-step instructions.
 
-If you host your Mastra application on your own infrastructure, you can still send observability data to Mastra platform using the [MastraPlatformExporter](https://mastra.ai/docs/observability/tracing/exporters/mastra-platform).
+If you host your Mastra application on your own infrastructure, you can still send observability data to Mastra platform using the [MastraPlatformExporter](https://mastra.ai/docs/observability/integrations/exporters/mastra-platform).