@mastra/mcp-docs-server 1.2.3-alpha.7 → 1.2.3

package/.docs/docs/agent-builder/memory.md

@@ -25,9 +25,11 @@ Observational memory lets the agent learn long-lived facts from past conversatio
 
 ## Observational memory model
 
-Observational memory runs an Observer and Reflector model on top of every conversation. The default model is `google/gemini-2.5-flash`, which requires a `GOOGLE_API_KEY` environment variable in any environment where the Builder agent will run. Mastra also falls back to `GOOGLE_GENERATIVE_AI_API_KEY`.
+Observational memory runs an Observer and Reflector model on top of every conversation. For Agent Builder agents, the default model is `openai/gpt-5-mini`, which requires an `OPENAI_API_KEY` environment variable in any environment where the Builder agent will run.
 
-To use a different model, set `observationalMemory.model` to any model ID supported by the Mastra model router (and provide the matching provider credentials):
+> **Note:** This default applies only to agents created through the Agent Builder. Core (non-builder) agents configured with `observationalMemory: true` keep the framework default `google/gemini-2.5-flash` (which uses `GOOGLE_API_KEY`, falling back to `GOOGLE_GENERATIVE_AI_API_KEY`).
+
+To use a different model, set `observationalMemory.model` to any model ID supported by the Mastra model router (and provide the matching provider credentials). An explicit model always wins over the Builder default:
 
 ```typescript
 new MastraEditor({

package/.docs/docs/agent-controller/overview.md

@@ -18,7 +18,7 @@ The AgentController gives you the runtime pieces to ship interactive agent appli
 - **Let users pick the right model for each step.** Per-mode [model management](https://mastra.ai/reference/agent-controller/agent-controller-class) switches models at runtime and tracks usage, which powers copilot UIs where users trade speed for capability.
 - **Delegate focused work to child agents.** [Subagents](https://mastra.ai/docs/agent-controller/subagents) run subtasks with constrained tools and can fork the parent conversation, so a research mode can spin off web search or code review without polluting the main thread.
 - **Drive a live UI from agent activity.** The [event system](https://mastra.ai/docs/agent-controller/session) emits typed events and coalesced display snapshots, so your TUI or web app reflects message updates, mode changes, and pending approvals in real time.
-- **Run long-lived autonomous agents.** Structured task lists, heartbeat handlers, and observational memory keep background task runners on track and let them learn across threads.
+- **Run long-lived autonomous agents.** Structured task lists, interval handlers, and observational memory keep background task runners on track and let them learn across threads.
 
 ## When to use the AgentController
 

package/.docs/docs/agents/agent-approval.md

@@ -357,6 +357,44 @@ For automatic tool resumption to work:
 
 Both approaches work with the same tool definitions. Automatic resumption triggers only when suspended tools exist in the message history and the user sends a new message on the same thread.
 
+## Resuming after a restart
+
+The examples above hold on to `stream.runId` between suspension and approval. That works while the process stays alive, but in production the approval often arrives later — after a page refresh, a server restart, or on a different server instance behind a load balancer.
+
+Use [`listSuspendedRuns()`](https://mastra.ai/reference/agents/listSuspendedRuns) to rediscover the pending run for a conversation from storage:
+
+```typescript
+// In the request handler that receives the user's decision
+const { runs } = await agent.listSuspendedRuns({
+  threadId: 'thread-123',
+  resourceId: 'user-456',
+})
+
+const run = runs[0]
+const toolCall = run?.toolCalls[0]
+
+if (run && toolCall) {
+  let stream
+  if (toolCall.requiresApproval) {
+    // Suspended by requireApproval — approve or decline the tool call
+    stream = await agent.approveToolCall({ runId: run.runId, toolCallId: toolCall.toolCallId })
+  } else {
+    // Suspended by suspend() — resume with the data the tool asked for
+    console.log('Tool asked:', toolCall.suspendPayload)
+    stream = await agent.resumeStream({ name: 'San Francisco' }, { runId: run.runId })
+  }
+  for await (const chunk of stream.textStream) process.stdout.write(chunk)
+}
+```
+
+Each returned run includes the suspended tool calls (`toolCallId`, `toolName`, `args`, and `requiresApproval`). Approval suspensions (`requiresApproval: true`) are answered with `approveToolCall()` / `declineToolCall()`, while `suspend()`-based suspensions carry their `suspendPayload` and expect `resumeStream()` with resume data — so you can rebuild the right UI for either flow without keeping any state in memory.
+
+`sendToolApproval()` uses the same storage-backed discovery automatically: when no active run is found in memory for the thread, it looks up the suspended run in storage before failing. If several suspended runs match the thread, pass a `toolCallId` to disambiguate.
+
+The same discovery is available over HTTP as `GET /agents/:agentId/suspended-runs` and in the client SDK as [`agent.listSuspendedRuns()`](https://mastra.ai/reference/client-js/agents), so browser-based approval UIs can rediscover pending runs directly.
+
+> **Note:** Suspended runs only survive restarts when your Mastra instance is configured with a persistent [storage provider](https://mastra.ai/docs/memory/storage). The default in-memory store loses snapshots when the process exits.
+
 ## Tool approval: Supervisor agents
 
 A [supervisor agent](https://mastra.ai/docs/agents/supervisor-agents) coordinates multiple subagents using `.stream()` or `.generate()`. When a subagent calls a tool that requires approval, the request propagates up through the delegation chain and surfaces at the supervisor level:

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

@@ -0,0 +1,286 @@
+# File-based agents
+
+**Added in:** `@mastra/core@1.48.0`
+
+> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+
+You can define an agent by file convention instead of constructing it in code. Mastra discovers a directory under `src/mastra/agents/<name>/`, assembles an [`Agent`](https://mastra.ai/reference/agents/agent), and registers it on your [`Mastra`](https://mastra.ai/reference/core/mastra-class) instance.
+
+## When to use file-based agents
+
+Use file-based agents when you want one directory per agent, with configuration, instructions, tools, skills, workspace files, and subagents grouped together.
+
+Keep using [`new Agent()`](https://mastra.ai/reference/agents/agent) in code when you need dynamic configuration, programmatic registration, or a shared agent instance across modules. Both approaches can coexist: code-registered agents are always present, and the bundler adds file-based agents when you run through the Mastra CLI.
+
+## Quickstart
+
+Create a directory for the agent and add a `config.ts`. Use `agentConfig` so the partial config is typed while sibling files supply the rest.
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  model: 'openai/gpt-5.5',
+  // instructions omitted -> taken from instructions.md
+  // tools omitted -> taken from tools/*.ts
+})
+```
+
+Add the agent instructions:
+
+```markdown
+You are a helpful weather assistant. Answer questions about current conditions and forecasts.
+```
+
+Add a tool. The filename becomes the tool key, so this file is exposed as `get_weather`.
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export default createTool({
+  id: 'get_weather',
+  description: 'Get the current weather for a city',
+  inputSchema: z.object({ city: z.string() }),
+  execute: async ({ context }) => ({ city: context.city, tempC: 21 }),
+})
+```
+
+Your `src/mastra/index.ts` stays the same. The discovered agent is registered automatically when you run the app through `mastra dev` or `mastra build`.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Agent } from '@mastra/core/agent'
+
+const supportAgent = new Agent({
+  id: 'support',
+  name: 'support',
+  instructions: 'You are a support agent.',
+  model: 'openai/gpt-5.5',
+})
+
+// `support` is registered in code; `weather` is discovered from the filesystem.
+export const mastra = new Mastra({
+  agents: { support: supportAgent },
+})
+```
+
+Start the app through the Mastra CLI:
+
+**npm**:
+
+```bash
+npx mastra dev
+```
+
+**pnpm**:
+
+```bash
+pnpm dlx mastra dev
+```
+
+**Yarn**:
+
+```bash
+yarn dlx mastra dev
+```
+
+**Bun**:
+
+```bash
+bun x mastra dev
+```
+
+## Folder structure
+
+The following table shows the supported file-based agent surface:
+
+| File / directory                        | Maps to                                                                                                                                   |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `agents/<name>/config.ts`               | Default export merged into the agent config. `id` and `name` default to `<name>`.                                                         |
+| `agents/<name>/instructions.md`         | The agent `instructions`. The file contents are inlined into generated code.                                                              |
+| `agents/<name>/tools/*.ts`              | Each default-exported [`createTool()`](https://mastra.ai/reference/tools/create-tool). The tool key defaults to the filename.             |
+| `agents/<name>/skills/*.ts`             | Each default-exported [`createSkill()`](https://mastra.ai/reference/agents/createSkill), added to the agent `skills`.                     |
+| `agents/<name>/skills/<skill>/SKILL.md` | A packaged skill. Frontmatter supplies `name` and `description`, the body is the instructions, and files under `references/` are inlined. |
+| `agents/<name>/skills/<skill>.md`       | A flat skill. The filename is the skill name and the body is the instructions.                                                            |
+| `agents/<name>/memory.ts`               | Default export: a [`Memory`](https://mastra.ai/reference/memory/memory-class) instance used as the agent `memory`.                        |
+| `agents/<name>/workspace.ts`            | Default export: a [`Workspace`](https://mastra.ai/reference/workspace/workspace-class) for the agent.                                     |
+| `agents/<name>/workspace/`              | Seed files mirrored into the agent's default workspace at build time.                                                                     |
+| `agents/<name>/subagents/<childId>/`    | A declared subagent with the same layout as an agent directory. Wired into the parent as a delegation tool named `<childId>`.             |
+
+Test files named `*.test.ts`, `*.spec.ts`, `*.test.js`, and `*.spec.js` are ignored during tool and skill discovery.
+
+## Add skills
+
+Add skills to a file-based agent by placing them under `agents/<name>/skills/`. Three layouts are supported, and they're inlined into the bundle at build time so the deployed agent doesn't read them from disk at runtime.
+
+- A `.ts` file can default-export `createSkill()`:
+
+  ```typescript
+  import { createSkill } from '@mastra/core/skills'
+
+  export default createSkill({
+    name: 'forecasting',
+    description: 'Use when the user asks about multi-day forecasts.',
+    instructions: 'Summarize the forecast day by day and call out precipitation.',
+  })
+  ```
+
+  > **Note:** Visit [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill) for the full API.
+
+- A packaged `SKILL.md` directory uses frontmatter for the name and description. Files under `references/` are inlined with the skill.
+
+  ```markdown
+  ---
+  name: severe-weather
+  description: Use when conditions include storms, flooding, or other hazards.
+  ---
+
+  Lead with the active alert, then give safety guidance.
+  ```
+
+- A flat `<skill>.md` file uses the filename as the skill name:
+
+  ```markdown
+  Always report temperatures in both Celsius and Fahrenheit.
+  ```
+
+Discovered skills merge with any `skills` in `config.ts`. On a name collision, `config.skills` wins and a warning is logged. If `config.skills` is a function, discovered skills are ignored with a warning because they can't be statically merged.
+
+## Add memory
+
+Give a file-based agent [memory](https://mastra.ai/docs/memory/overview) by adding a `memory.ts` that default-exports a [`Memory`](https://mastra.ai/reference/memory/memory-class) instance:
+
+```typescript
+import { Memory } from '@mastra/memory'
+
+export default new Memory()
+```
+
+The exported instance becomes the agent's `memory`. You can also set `memory` directly in `config.ts`. `config.memory` wins over `memory.ts`, and a warning is logged when both are present. If neither is present, the agent has no memory, which is the default.
+
+## Add a workspace
+
+When a file-based agent is discovered through `mastra dev` or `mastra build`, it gets a default workspace unless `config.workspace` or `workspace.ts` supplies one. The default workspace uses a contained filesystem and shell sandbox rooted at a per-agent `workspace/` directory in the bundle.
+
+To customize it, add a `workspace.ts` that default-exports a [`Workspace`](https://mastra.ai/reference/workspace/workspace-class):
+
+```typescript
+import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'
+
+export default new Workspace({
+  name: 'weather-workspace',
+  filesystem: new LocalFilesystem({ basePath: './data/weather' }),
+  sandbox: new LocalSandbox({ workingDirectory: './data/weather' }),
+})
+```
+
+You can also set `workspace` directly in `config.ts`. `config.workspace` wins over `workspace.ts`, and `workspace.ts` wins over the default workspace.
+
+### Seed files
+
+Add a `workspace/` directory to ship files with the agent. Mastra mirrors every file under it into the agent's default workspace at build time, so the agent starts with those files on disk:
+
+```text
+src/mastra/agents/weather/
+  config.ts
+  workspace/
+    README.md
+    data/cities.json
+```
+
+Seed files are copied into the bundle next to the running server. Commit the starting files alongside the agent that uses them.
+
+## Add subagents
+
+A file-based agent can declare **subagents**, specialist child agents it can delegate to. Add a `subagents/` directory under the agent, with one directory per subagent. Each subagent directory has the same layout as a top-level agent: `config.ts`, `instructions.md`, `tools/`, `skills/`, `memory.ts`, `workspace.ts`, and `workspace/`.
+
+```text
+src/mastra/agents/
+  supervisor/
+    config.ts
+    instructions.md
+    subagents/
+      researcher/
+        config.ts
+        instructions.md
+        tools/
+          search.ts
+```
+
+Each subagent is assembled as its own agent and wired into the parent's `agents` map. The agent loop lowers it into a model-visible delegation tool. The tool name is the bare directory name, so the example above exposes `researcher` to the supervisor.
+
+A subagent's `config.ts` must set a non-empty `description`. The description is what the model sees when deciding whether to delegate, so the build fails if it's missing.
+
+```typescript
+import { agentConfig } from '@mastra/core/agent'
+
+export default agentConfig({
+  model: 'openai/gpt-5.5',
+  description: 'Researches a topic and returns cited findings.',
+})
+```
+
+Subagents are isolated. A subagent inherits nothing from its parent. Its tools, skills, and workspace come only from its own directory, and any absent slot falls back to the same framework defaults as a top-level agent.
+
+Subagents are one level deep. A `subagents/` directory nested inside a subagent is ignored with a warning.
+
+Naming rules:
+
+- A subagent id that collides with one of the parent's tool keys is a build error.
+- A duplicate subagent id under the same parent is a build error.
+- If a subagent id also exists in the parent's `config.agents`, the `config.agents` entry wins and logs a warning.
+- If `config.agents` is a function, discovered subagents are ignored with a warning because they can't be statically merged.
+
+## Precedence rules
+
+File-based and code-based agents coexist with deterministic rules:
+
+- **Code wins on name collisions:** If an agent name exists in both code and the filesystem, the code-registered agent is kept and a warning is logged.
+- **A folder can hold a code agent:** If `config.ts` exports `new Agent({...})`, that instance is used as-is. Sibling `instructions.md`, `tools/`, `skills/`, `memory.ts`, `workspace.ts`, and `subagents/` entries are ignored with warnings.
+- **Instructions:** Dynamic function instructions in `config.ts` win over `instructions.md`. Otherwise, `instructions.md` wins over a static `instructions` string. If neither is present, the build fails for that agent.
+- **Model:** A missing `model` fails the build and names the agent directory.
+- **Tools:** Tools from `tools/*.ts` merge with `config.tools`. On a key collision, `config.tools` wins and a warning is logged. If `config.tools` is a function, discovered tools are ignored with a warning.
+- **Skills:** Skills from `skills/` merge with `config.skills`. On a name collision, `config.skills` wins and a warning is logged. If `config.skills` is a function, discovered skills are ignored with a warning.
+- **Memory:** `config.memory` wins over `memory.ts`, and a warning is logged when both are present. If neither is set, the agent has no memory.
+- **Workspace:** `config.workspace` wins over `workspace.ts`, which wins over the default workspace.
+- **Subagents:** Subagents from `subagents/` merge with `config.agents`. On an id collision, `config.agents` wins and a warning is logged. A subagent id that collides with a tool key, or a duplicate subagent id, is a build error.
+
+## What happens at build time
+
+File-based agents are discovered by the Mastra **bundler**, the step that runs under `mastra dev` and `mastra build`.
+
+File-based agents are registered only when your app runs through the Mastra CLI. If you import your `mastra` instance directly, `agents/<name>/` directories aren't discovered.
+
+When you consume Mastra as a library, register those agents in code instead of relying on file discovery:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Agent } from '@mastra/core/agent'
+
+const weather = new Agent({
+  id: 'weather',
+  name: 'weather',
+  instructions: 'You are a helpful weather assistant.',
+  model: 'openai/gpt-5.5',
+})
+
+export const mastra = new Mastra({
+  agents: { weather },
+})
+```
+
+## Related
+
+- [Agents overview](https://mastra.ai/docs/agents/overview)
+- [Tools](https://mastra.ai/docs/agents/using-tools)
+- [Skills](https://mastra.ai/docs/agents/skills)
+- [Memory](https://mastra.ai/docs/memory/overview)
+- [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)
+- [Workspace](https://mastra.ai/docs/workspace/overview)
+- [Studio overview](https://mastra.ai/docs/studio/overview)
+- [`Agent` reference](https://mastra.ai/reference/agents/agent)
+- [`createTool()` reference](https://mastra.ai/reference/tools/create-tool)
+- [`createSkill()` reference](https://mastra.ai/reference/agents/createSkill)
+- [`Memory` reference](https://mastra.ai/reference/memory/memory-class)
+- [`Workspace` reference](https://mastra.ai/reference/workspace/workspace-class)

package/.docs/docs/agents/heartbeats.md

@@ -0,0 +1,211 @@
+# Heartbeats
+
+**Added in:** `@mastra/core@1.46.0`
+
+> **Beta:** This feature is in alpha. Breaking changes may occur without a major version bump until the API is stable.
+
+A heartbeat runs an agent on a cron schedule. On each fire, Mastra sends a prompt to the agent, either as a [signal](https://mastra.ai/docs/agents/signals) into a thread or as a threadless `agent.generate()` run. Use heartbeats for recurring agent work such as daily summaries, periodic checks, or scheduled nudges into a conversation.
+
+Heartbeats are persisted, so they survive restarts and redeploys. Manage them at runtime through `mastra.heartbeats`, the canonical create, read, update, and delete (CRUD) surface.
+
+## Prerequisites
+
+Heartbeats require a [storage](https://mastra.ai/docs/memory/storage) adapter that implements the schedules domain, for example `@mastra/libsql`. Without one, `mastra.heartbeats.create()` throws.
+
+## Quickstart
+
+The following heartbeat runs the `pinger` agent every hour. It has no thread, so each fire is an isolated `agent.generate()` run.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { Agent } from '@mastra/core/agent'
+import { LibSQLStore } from '@mastra/libsql'
+
+const pinger = new Agent({
+  id: 'pinger',
+  name: 'Pinger',
+  instructions: 'Report the current system status in one sentence.',
+  model: 'openai/gpt-5.5',
+})
+
+const mastra = new Mastra({
+  agents: { pinger },
+  storage: new LibSQLStore({ url: 'file:./mastra.db' }),
+})
+
+await mastra.heartbeats.create({
+  agentId: 'pinger',
+  cron: '0 * * * *',
+  prompt: 'Give me a status update.',
+})
+```
+
+Mastra starts the scheduler the first time a heartbeat is created, then fires the agent on the cron you specify.
+
+## Cadence
+
+Heartbeats fire on a cron expression. The `cron` field accepts a standard 5-, 6-, or 7-part cron expression, and it's validated when you create or update the heartbeat.
+
+Croner nicknames also work, for example `@hourly`, `@daily`, `@weekly`, `@monthly`, and `@midnight`. For day-and-time combinations, write the cron field directly:
+
+```typescript
+// Every weekday at 9am
+await mastra.heartbeats.create({
+  agentId: 'pinger',
+  cron: '0 9 * * 1-5',
+  prompt: 'Start-of-day check.',
+})
+```
+
+Set `timezone` to an IANA timezone, for example `America/New_York`, so fire times don't depend on the host's locale. When omitted, the cron resolves against the host's local timezone.
+
+For more readable cron construction, you can use a userland builder such as [`cron-time-generator`](https://www.npmjs.com/package/cron-time-generator) and pass its output to `cron`.
+
+## Threadless and threaded heartbeats
+
+A heartbeat fires in one of two modes, decided by whether you pass a `threadId`.
+
+### Threadless
+
+Without a `threadId`, each fire is an isolated `agent.generate()` run. Nothing is written to a conversation thread. This is the simplest mode and suits status checks, reports, and other work that doesn't need conversation context.
+
+### Threaded
+
+With a `threadId`, the heartbeat sends a [signal](https://mastra.ai/docs/agents/signals) into that thread, so the prompt joins the agent's conversation. Threaded heartbeats require a `resourceId` alongside the `threadId`.
+
+```typescript
+await mastra.heartbeats.create({
+  agentId: 'pinger',
+  cron: '0 9 * * *',
+  prompt: 'Summarize anything new since yesterday.',
+  threadId: 'thread-123',
+  resourceId: 'user-456',
+})
+```
+
+Threaded heartbeats accept extra fields that control how the signal behaves. They mirror the options [`agent.sendSignal`](https://mastra.ai/docs/agents/signals) accepts and stay JSON-serializable so they persist with the schedule.
+
+- `signalType`: the [signal type](https://mastra.ai/docs/agents/signals) to send, for example `notification` or `system-reminder`. Defaults to `notification`.
+- `tagName`: the XML tag the signal renders as. Defaults to `heartbeat`, so a fire surfaces to the agent as `<heartbeat>…</heartbeat>`.
+- `attributes`: values rendered onto the signal's XML tag.
+- `ifActive`: behavior when the thread is already streaming, as `{ behavior, attributes }`. `behavior` is one of `deliver`, `persist`, or `discard`.
+- `ifIdle`: behavior when the thread is idle, as `{ behavior, attributes, streamOptions }`. `behavior` is one of `wake`, `persist`, or `discard`. `streamOptions.requestContext` is applied to the woken run.
+
+These fields require a `threadId`. Passing them on a threadless heartbeat throws.
+
+```typescript
+await mastra.heartbeats.create({
+  agentId: 'pinger',
+  cron: '0 9 * * *',
+  prompt: 'Summarize anything new since yesterday.',
+  threadId: 'thread-123',
+  resourceId: 'user-456',
+  tagName: 'check-in', // renders as <check-in>…</check-in>
+  attributes: { source: 'cron' },
+  ifActive: { behavior: 'discard' }, // skip if the thread is mid-stream
+  ifIdle: {
+    behavior: 'wake', // wake the agent if the thread is idle
+    streamOptions: { requestContext: { locale: 'en-US' } },
+  },
+})
+```
+
+`providerOptions` are merged into the signal payload on every fire and apply to both threaded and threadless heartbeats.
+
+## Managing heartbeats
+
+Use `mastra.heartbeats` for all heartbeat operations. To scope to a single agent, pass `agentId` to `create` or `list`.
+
+```typescript
+// Create
+const hb = await mastra.heartbeats.create({
+  agentId: 'pinger',
+  cron: '0 * * * *',
+  prompt: 'Status check.',
+})
+
+// Read
+await mastra.heartbeats.get(hb.id)
+await mastra.heartbeats.list({ agentId: 'pinger' })
+
+// Update — changing cron or timezone recomputes the next fire time
+await mastra.heartbeats.update(hb.id, { cron: '*/30 * * * *' })
+
+// Pause and resume
+await mastra.heartbeats.pause(hb.id)
+await mastra.heartbeats.resume(hb.id)
+
+// Fire once now, off-schedule
+await mastra.heartbeats.run(hb.id)
+
+// Delete
+await mastra.heartbeats.delete(hb.id)
+```
+
+A few rules worth knowing:
+
+- `pause` and `resume` are durable and idempotent. A paused heartbeat survives restarts, and `resume` recomputes the next fire time from now rather than firing backlogged runs.
+- `run` fires the heartbeat once immediately without affecting its schedule.
+- `list` filters by `agentId`, `threadId`, `resourceId`, and `name`.
+
+### Custom IDs
+
+By default `create` generates a random `hb_<uuid>` id. Pass `id` to choose a stable one, for example when you want a predictable handle to look up, update, or delete later:
+
+```typescript
+await mastra.heartbeats.create({
+  id: 'nightly-summary',
+  agentId: 'pinger',
+  cron: '0 9 * * *',
+  prompt: 'Summarize anything new since yesterday.',
+})
+// stored as `hb_nightly-summary`
+```
+
+The id is normalized to `hb_<slug>`: the `hb_` prefix is added if missing and the rest is slugified. Creating a heartbeat with an id that already exists throws, so use `update` to change an existing one.
+
+### From the client
+
+The same operations are available from `@mastra/client-js` over the server routes, so you can manage heartbeats from a separate process or a UI.
+
+## Lifecycle hooks
+
+Hooks let you run code at key points in a heartbeat's lifecycle, for example to compute fire-time parameters or react to the outcome. Configure them on the `Mastra` constructor under `heartbeat`. The hooks are a single flat bundle that runs for every agent's heartbeats; each hook context carries the firing `agentId`, so branch on it when you need per-agent behavior. Hooks live at the `Mastra` level so they apply to both code-defined and stored agents.
+
+```typescript
+const mastra = new Mastra({
+  agents: { pinger },
+  storage: new LibSQLStore({ url: 'file:./mastra.db' }),
+  heartbeat: {
+    prepare: async ({ agentId, heartbeat, trigger }) => {
+      // Return overrides, null to skip this fire, or undefined for defaults
+      return { prompt: `Status as of ${trigger.firedAt.toISOString()}` }
+    },
+    onFinish: async ({ agentId, outcome, runId }) => {
+      // Runs on any non-error, non-abort outcome
+    },
+    onError: async ({ agentId, phase, error }) => {
+      // Runs when prepare, the signal, or the agent run threw
+    },
+    onAbort: async ({ agentId, runId }) => {
+      // Runs when the run was aborted mid-stream
+    },
+  },
+})
+```
+
+The hooks are:
+
+- `prepare`: runs before the fire. Return an object to override fire-time parameters such as `prompt` or `threadId`, `null` to skip the fire, or `undefined` to use the stored defaults.
+- `onFinish`: runs once per trigger that reached a non-error, non-abort terminal state.
+- `onError`: runs when `prepare`, the signal, or the agent run threw.
+- `onAbort`: runs when the run was aborted mid-stream.
+
+Every hook context includes `agentId` (the agent the heartbeat fired for) alongside `heartbeat` and `trigger`.
+
+Hook exceptions are caught and logged. They never re-route the worker or trigger another hook.
+
+## Related
+
+- [Signals](https://mastra.ai/docs/agents/signals): the delivery mechanism behind threaded heartbeats.
+- [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows): run a workflow, rather than an agent, on a cron schedule.

package/.docs/docs/getting-started/project-structure.md

@@ -2,13 +2,13 @@
 
 Your new Mastra project, created with the `create mastra` command, comes with a predefined set of files and folders to help you get started.
 
-Mastra is a framework, but it's **unopinionated** about how you organize or colocate your files. The CLI provides a sensible default structure that works well for most projects, but you're free to adapt it to your workflow or team conventions. You could even build your entire project in a single file if you wanted! Whatever structure you choose, keep it consistent to ensure your code stays maintainable and straightforward to navigate.
+Mastra is a framework, but it's mostly **unopinionated** about how you organize or colocate your files. The CLI provides a sensible default structure that works well for most projects, but you're free to adapt it to your workflow or team conventions. You could even build your entire project in a single file if you wanted! Whatever structure you choose, keep it consistent to ensure your code stays maintainable and straightforward to navigate.
 
 ## Default project structure
 
 A project created with the `create mastra` command looks like this:
 
-```text
+```bash
 src/
 ├── mastra/
 │   ├── agents/
@@ -25,21 +25,25 @@ src/
 └── tsconfig.json
 ```
 
-> **Tip:** Use the predefined files as templates. Duplicate and adapt them to quickly create your own agents, tools, workflows, etc.
+Use the predefined files as templates. Duplicate and adapt them to quickly create your own agents, tools, workflows, etc.
 
 ### Folders
 
-Folders organize your agent's resources, like agents, tools, and workflows.
-
-| Folder                 | Description                                                                                                                              |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `src/mastra`           | Entry point for all Mastra-related code and configuration.                                                                               |
-| `src/mastra/agents`    | Define and configure your agents - their behavior, goals, and tools.                                                                     |
-| `src/mastra/workflows` | Define multi-step workflows that orchestrate agents and tools together.                                                                  |
-| `src/mastra/tools`     | Create reusable tools that your agents can call                                                                                          |
-| `src/mastra/mcp`       | (Optional) Implement custom MCP servers to share your tools with external agents                                                         |
-| `src/mastra/scorers`   | (Optional) Define scorers for evaluating agent performance over time                                                                     |
-| `src/mastra/public`    | (Optional) Contents are copied into the `.build/output` directory during the build process, making them available for serving at runtime |
+Mastra recommends organizing your code into the following folders:
+
+| Folder                 | Description                                                             |
+| ---------------------- | ----------------------------------------------------------------------- |
+| `src/mastra`           | Entry point for all Mastra-related code and configuration.              |
+| `src/mastra/agents`    | Define and configure your agents - their behavior, goals, and tools.    |
+| `src/mastra/workflows` | Define multi-step workflows that orchestrate agents and tools together. |
+| `src/mastra/tools`     | Create reusable tools that your agents can call                         |
+| `src/mastra/mcp`       | Implement custom MCP servers to share your tools with external agents   |
+| `src/mastra/scorers`   | Define scorers for evaluating agent performance over time               |
+
+There are two special folder conventions in Mastra:
+
+- `src/mastra/agents/<name>`: You can define an agent by file convention instead of constructing it in code. Learn more in the [file-based agents](https://mastra.ai/docs/agents/file-based-agents) guide.
+- `src/mastra/public`: Contents are copied into the `.build/output` directory during the build process, making them available for serving at runtime.
 
 ### Top-level files