> Opened by @DSchau
## What
- `docs/package.json`: adds `packageManager` with the same pnpm pin as
the root (`pnpm@11.21.0+sha512…`). Vercel, Corepack and editors read
this field to choose the installer, so the docs project now declares
pnpm itself instead of depending on Vercel config.
- `docs/vercel.json`: sets `installCommand: "pnpm install
--frozen-lockfile"`. This is the same command
`packages/playground/vercel-preview/vercel.json` already uses, and it
makes the deploy explicit.
## Why
#28417 changed six docs dependencies to `catalog:`: `react`,
`react-dom`, `lucide-react`, `oxfmt`, `tsx` and `vitest`. Only pnpm
(with `pnpm-workspace.yaml`) can resolve that protocol. The
`mastra-docs-1.x` Vercel deploy passed on `52db47cd` and has failed on
every main commit since `ce5d4731` (#28417). `docs/` has neither a
lockfile nor a `packageManager` field, so a Vercel project rooted at
`docs` has to guess the installer. This PR keeps the catalog change and
pins docs to pnpm.
## Proof
- A local `pnpm build` in `docs/` passes on main (exit 0, 975 llms.txt
files generated).
- `pnpm install --frozen-lockfile` with the new field: "Already up to
date" on pnpm 11.21.0, no warnings about the docs package.
- `docs/package.json` has 0 `catalog:` entries at `52db47cd` and 6 at
main.
## Unverified
- I couldn't read the Vercel build logs, so the exact install error
isn't confirmed. This PR's `mastra-docs-1.x` preview is the real test.
- For Vercel to honor the exact pnpm version in `packageManager`, the
project needs `ENABLE_EXPERIMENTAL_COREPACK=1`. Without it, Vercel uses
its bundled pnpm.
- If the Vercel Root Directory is `docs`, "Include files outside the
root directory" must stay enabled so pnpm can see the workspace root.
## Risk: low
Config only, scoped to the docs package. Two keys to revert.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
## ELI5
The docs site uses package versions that only pnpm understands. This
change tells Vercel to use pnpm when it installs the docs dependencies,
and pins the pnpm version.
## Changes
- Added the pnpm 11.21.0 package-manager pin to `docs/package.json`.
- Set `installCommand` to `pnpm install --frozen-lockfile` in
`docs/vercel.json` and in the generator that creates it. This keeps the
generated configuration aligned with its source.
The supplied information reports a local build and install, but does not
verify the Vercel preview. Vercel build logs and review finding counts
were not provided.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com>
## Summary
The `@mastra/connect` end-user connections documentation was supposed to
ship only on the docs PR
[#27334](https://github.com/mastra-ai/mastra/pull/27334), but PRs #26923
and #26928 brought the following end-user connections docs content into
main as part of the code merges:
-
`docs/src/content/en/docs/mastra-platform/connect/end-user-connections.mdx`
(new file, from #26923)
- `docs/src/content/en/reference/connect/user-connect-routes.mdx` (new
file, from #26923)
- Sidebar entries for both pages
- `resourceId` option added to `credential.mdx` (from #26923)
- `resourceId` and `connectPrompt` options added to `tools.mdx` (from
#26923 and #26928)
This PR removes all of that so #27334 owns the complete end-user
connections documentation set.
The code APIs remain shipped on main unchanged — only the docs are
reverted. The docs PR already carries complete versions of every file
touched here and will re-introduce them atomically when it merges.
## Verification
- `docs/connect-project-provider-policy` branch (PR #27334) still
contains `end-user-connections.mdx`, `user-connect-routes.mdx`, the
sidebar entries, and the fuller `resourceId` / `connectPrompt`
documentation on `tools.mdx` and `credential.mdx`.
- No references to `end-user-connections`, `user-connect-routes`, or
`userConnectRoutes` remain in `docs/src/content/en` after this revert.
- Diff is 2 insertions / 271 deletions across 6 files.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
## ELI5
This PR removes documentation about end-user connections and redirects
the old page URLs to related Connect pages. It also removes related
option details from the reference docs; the PR description says the code
APIs do not change.
## Summary
- Deleted the end-user connections guide and the `userConnectRoutes()`
reference page.
- Removed both pages from their sidebars.
- Removed `resourceId` from the documented `credential()` options.
- Removed `resourceId` and `connectPrompt` from the documented `tools()`
options.
- Added redirects from the deleted pages and their `/llms.txt` routes to
related Connect pages.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
## Why
The Signals documentation was one 555-line page under **Harness** that
tried to cover four different jobs at once: explaining what signals are,
showing how to send them, documenting state signals and notifications,
and explaining providers and multi-process deployment. Readers had to
scan a single long page to find the one task they cared about, and
reference-level details were mixed in with the guide.
This reorganizes Signals as a first-class section under **Extend** and
gives each reader task its own page. The conceptual spine is **signals
are input; thread streams are output**. `Agent` stays the primary API;
the AgentController `Session` surface is shown as a higher-level
mapping, not the default.
## What changed
- Added seven Signals guides under `/docs/signals`:
- **Overview**: when to use signals, the thread/run/signal/thread-stream
model, Quickstart, and choosing an API surface
- **Thread streams**: subscribe-before-send, stored history, chunks,
approvals, filtering, reconnect, and replay boundaries
- **Sending signals**: message and typed-signal input, delivery timing,
payloads, cancellation, and the Agent-versus-Session mapping
- **State signals**: snapshots and deltas, processor-computed state,
deduplication, persistence, and built-in uses
- **Notifications**: durable inbox records, deduplication/coalescing,
delivery policies, dispatch, retries, and the inbox tool
- **Signal providers**: subscriptions, polling, webhooks, lifecycle
hooks, processors/tools, and production concerns
- **Running across processes**: leases, remote routing, delivery
guarantees, crashes, serverless, and shutdown
- Moved the section from **Harness** to **Extend**, immediately after
**Channels**.
- Added `reference/signals/notifications` for `NotificationRecord`,
priorities, statuses, delivery decisions, policy evaluation, dispatch
configuration, and delivered-signal metadata.
- Added `reference/signals/thread-events` for the public
`subscribeThreadEvents()` surface and `AgentThreadEvent`. The internal
thread-runtime event union is deliberately not documented as public API.
- Added the `thread-history` chunk to the `ChunkType` reference,
including `messages`, `hasMore`, and the `withInitialHistory` condition.
- Moved the Mastra Code cross-agent setup to
`docs/src/mastra-code/configuration.mdx` and left a pointer from the
Signals overview.
- Updated the docs and reference sidebars, inbound links, and page-level
redirects from the old Harness routes.
- Folded the separate “Signals in the agent loop” draft page into the
pages that own its material (Sending signals, Thread streams, Running
across processes, Processors, and the tracing overview).
## Test plan
- [x] `pnpm --filter mastra-docs test -- --reporter=dot` — 170 tests
passed
- [x] `pnpm --filter mastra-docs validate:frontmatter` — 679 files
passed
- [x] `pnpm --filter mastra-docs validate:reference-sidebar` — sort
order passed
- [x] `pnpm --filter mastra-docs validate:sidebar-docs` — all docs
linked
- [x] `pnpm --filter mastra-docs format:mdx:check` — 717 MDX files
checked
- [x] `pnpm --filter mastra-docs lint:remark` — passed
- [x] `pnpm --filter mastra-docs exec oxfmt-mdx --check
src/mastra-code/configuration.mdx` — passed
- [x] `pnpm --filter mastra-docs build` — production build succeeded
- [x] `git diff --check` — clean
Docs-only change. No runtime, package, dependency, or changeset changes.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->
## ELI5
This PR moves the Signals documentation into a set of task-based guides
and updates links from the old pages. It also adds references for
notifications and thread events, so readers can find details about how
signals and thread updates work.
## Changes
- Adds seven guides under **Extend** for the Signals model, thread
streams, sending signals, state signals, notifications, providers, and
multi-process setup.
- Adds reference pages for notifications and thread events, and
documents the `thread-history` stream chunk.
- Updates the sidebars, links, and permanent redirects for the new
documentation paths.
- Moves Mastra Code cross-agent setup guidance to its configuration
page.
- Updates processor documentation with a reactive signal example and
documents the `computeStateSignal` processor hook.
## Validation
The PR author reports that the documentation tests, validators,
formatting checks, build, and `git diff --check` passed. The reported
test run had 170 tests. These results were not independently verified.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: mastracode <284800079+mastra-platform[bot]@users.noreply.github.com>
## Description
Reverts the documentation portion of #23077 (the `@mastra/mcp` code and
changeset are untouched).
- Deletes `docs/src/content/en/docs/connections/connect-mcp-client.mdx`
(the "Connect your MCP client to Mastra (draft)" page, which described
an unimplemented `mastra mcp` launcher).
- Restores `docs/src/content/en/docs/sidebars.js` so the Connections
sidebar is a flat `MCP` doc entry again instead of the `Tools & MCP`
category that #23077 introduced. The file is byte-identical to its
pre-#23077 state.
- Restores `docs/src/content/en/reference/tools/mcp-server.mdx` to its
pre-#23077 state (removes the "Operate a remote Mastra server" section,
which the removed page linked to). Byte-identical to pre-#23077.
- Adds a permanent redirect `/docs/connections/connect-mcp-client` →
`/docs/connections/mcp` in `vercel.redirects.json` (the page was already
live on mastra.ai) and regenerates `vercel.json`, which also produces
the `/llms.txt` companion redirect.
Verification (from `docs/`): `pnpm format:check`, `pnpm validate`,
redirect generator / move-doc / delete-doc script tests (88 passed),
`git diff --check`, and `pnpm build`. A repo-wide grep for
`connect-mcp-client`, `operate-a-remote-mastra-server`, and "Connect
your MCP client" only matches the new redirect entries.
## Related issue(s)
Reverts docs from #23077. Requested in Slack (#growth-docs).
## Type of change
- [x] Documentation update
## Checklist
- [x] I have linked the related issue(s) in the description above
- [x] I have made corresponding changes to the documentation (if
applicable)
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have addressed all Coderabbit comments on this PR
Link to Devin session:
https://app.devin.ai/sessions/abf500fe19fe4706b9b274dc6ade0cd2
Open in Devin Desktop:
https://app.devin.ai/desktop/session/abf500fe19fe4706b9b274dc6ade0cd2?variant=devin
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR removes an unfinished MCP client documentation page and restores
the previous MCP documentation. Old links now redirect to the current
MCP page.
## Changes
- Deleted the draft `connect-mcp-client.mdx` page.
- Restored the Connections sidebar structure.
- Removed the remote Mastra server section from the MCP server
reference.
- Added permanent redirects for:
- `/docs/connections/connect-mcp-client`
- `/docs/connections/connect-mcp-client/llms.txt`
- Regenerated `vercel.json`.
- Left `@mastra/mcp` code and its changeset unchanged.
## Verification
Formatting, validation, redirect tests, diff checks, and the
documentation build reportedly passed.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: alex <alex@mastra.ai>
## Summary
- remove all 10 tutorials and the Tutorials category from the Guides
sidebar
- replace docs links to migrated tutorials with their new blog URLs
- add permanent external redirects for every former tutorial route and
regenerate `vercel.json`
- remove the screenshot asset after moving it to the website repository
Companion blog PR: https://github.com/mastra-ai/mastra-website/pull/1324
## Verification
- `pnpm run validate`
- `pnpm run format:check`
- `pnpm test -- scripts/__tests__/delete-doc.test.ts
scripts/__tests__/generate-vercel-redirects.test.ts` (144 tests)
- `pnpm run lint:prose` runs, but Vale reports 6 pre-existing errors in
`docs/src/content/en/reference/processors/processor-interface.mdx`;
Remark passes
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
The documentation moved ten tutorials to the Mastra blog. Old links now
redirect to the new blog posts, so existing bookmarks continue to work.
## Changes
- Removed ten tutorial pages and the Tutorials sidebar category.
- Updated related documentation links to the blog.
- Added permanent redirects for former tutorial routes.
- Regenerated `vercel.json`.
- Removed the migrated screenshot asset.
## Validation
- `pnpm run validate`
- `pnpm run format:check`
- Targeted tests
- Remark passed.
- Vale reported six pre-existing errors.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Moves the multi-agent systems and streaming guides into a new Guides
category at the bottom of the main docs navigation. Existing
concept-guide URLs continue to work through generated redirects, and the
contextual sidebar keeps Multi-agent systems as the landing-page label.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
The documentation now groups the multi-agent systems and streaming pages
under **Guides**. Old links still work and redirect users to the new
pages.
## Changes
- Added a **Guides** section under **More** in the main documentation
sidebar.
- Added contextual sidebar support for custom labels such as
**Multi-agent systems**.
- Moved guide navigation content from **Concepts** and updated the
Guides sidebar categories.
- Updated internal links to the new `/docs/guides/...` routes.
- Added redirects for old concept-guide URLs, including `llms.txt`
routes.
- Expanded the streaming guide with agent and workflow streams, event
types, writer APIs, custom events, and TypeScript examples.
- Added tests for contextual sidebar labels.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
This removes tutorials that duplicate maintained documentation while
preserving the useful MCP publishing guidance on the canonical MCP page.
| Tutorial | Action | Rationale |
| --- | --- | --- |
| Slack Assistant | Remove | The Slack channel documentation covers the
same setup and provides more complete guidance for authentication,
events, interactivity, and deployment. |
| WhatsApp Chat Bot | Remove | The tutorial uses an older manual webhook
implementation. The WhatsApp channel adapter is the supported path and
includes the relevant setup in one maintained page. |
| Web Search | Remove | The built-in `webSearchTool` documentation
provides the current provider-agnostic approach and supports the
maintained provider integrations. |
| Publishing an MCP Server | Move into the MCP overview | Publishing is
too narrow for a standalone tutorial, but the stdio entry point, package
configuration, and client setup remain useful beside the canonical MCP
server documentation. |
| Chef Michel | Remove | This is primarily a themed version of the
standard agent quickstart and does not teach a distinct Mastra concept.
|
| Stock Agent | Remove | This duplicates the custom tool quickstart. It
also reads the previous trading day's `4. close` value but returns it as
`currentPrice` and presents it as the current stock price, which can
give readers stale market data under an inaccurate label. |
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR removes old tutorials that duplicate maintained documentation.
It keeps selected tutorials, moves MCP publishing content to the main
MCP page, and redirects old links to current pages.
## Changes
- Removed the Slack Assistant, WhatsApp Chat Bot, Web Search, Chef
Michel, Stock Agent, and Publishing an MCP Server tutorials.
- Retained the Research Assistant, Code Review Bot, and Docs Manager
tutorials.
- Added MCP stdio server publishing instructions to the MCP overview
page.
- Pinned the MCP subprocess example to version `1.0.0`.
- Updated MCP example links.
- Added permanent redirects for removed guide routes and `.llms.txt`
routes.
- Removed the WhatsApp guide from the feature-versioning map.
- Added redirect regression coverage.
- No tests were added.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Moves the migration guides from Guides into Reference, updates links and
redirects to the new paths, and keeps the MCP docs server migration
lookup aligned with the move.\n\nExisting migration URLs continue to
redirect to their new Reference locations.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
Migration guides moved to a clearer Reference section. Old guide links
still work because they redirect to the new locations. The MCP docs
server now uses the new location.
## Changes
- Moved migration guides from `Guides` to `Reference`.
- Updated internal links and sidebar navigation.
- Added package metadata to migration pages.
- Added permanent redirects from `/guides/migrations/:path*` to
`/reference/migrations/:path*`, including `llms.txt` routes.
- Updated `@mastra/mcp-docs-server` to load migrations from
`.docs/reference/migrations`.
- Added a patch changeset for `@mastra/mcp-docs-server`.
- Clarified migration compatibility wording and fixed compound
modifiers.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
- add a top-level Observe section for tracing, metrics, evals, and
datasets
- keep Production focused on server and deployment docs
- merge observability configuration and storage guidance into the
overview
- place Tracing directly after Overview and nest integrations under
Tracing
- redirect the removed configuration and storage routes to the merged
overview
## Testing
- `pnpm --dir docs build`
- `pnpm --dir docs validate`
- `pnpm --dir docs lint:prose` (Remark passes; Vale reports a
pre-existing issue in
`docs/src/content/en/docs/server/mastra-client.mdx`)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
The documentation now has one clear place for observability setup and
storage guidance. Older page and `llms.txt` links redirect to the new
overview.
## Changes
- Added a top-level **Observe** section to the documentation sidebar.
- Grouped tracing, metrics, evaluations, and datasets under **Observe**.
- Moved **Deployment** earlier in the **Production** section.
- Merged observability configuration and storage guidance into
`observability/overview`.
- Kept **Tracing** after **Overview** and nested integrations under it.
- Updated links to use the merged overview and page anchors.
- Added permanent redirects for the removed configuration and storage
routes, including `llms.txt` routes.
- Removed the standalone observability configuration and storage pages.
## Validation
- Documentation build passed.
- Remark passed.
- Vale reported a pre-existing issue in
`docs/src/content/en/docs/server/mastra-client.mdx`.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Lennart <lekoarts@gmail.com>
## Summary
- move dataset and experiment docs from `/docs/evals/datasets/*` to
`/docs/datasets/*`
- place Datasets last in the Production sidebar group and update docs
and Studio links
- add direct redirects for old dataset routes and regenerate
`vercel.json` without dataset redirect chains
## Validation
- `pnpm build`
- scoped Remark and Vale lint for changed docs
- `pnpm --filter ./packages/playground lint` (passes with existing
warnings)
- dataset redirect-chain check across all six dataset-related entries in
generated `vercel.json`
Full `pnpm lint:prose` also reports four existing Vale errors in
untouched docs pages. A strict global wildcard expansion finds
pre-existing chains through broad version redirects such as
`/docs/v1/:path* -> /docs/:path*`; this PR does not add any dataset
redirect chains.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
The PR moves dataset documentation to a clearer location. It updates
links and redirects so old pages still work.
## Changes
- Moved dataset documentation from `/docs/evals/datasets/*` to
`/docs/datasets/*`.
- Added Datasets as a top-level Production sidebar section.
- Updated documentation and Studio links to use the new paths.
- Updated Playground dataset and experiment links.
- Added direct redirects for legacy dataset routes and `/llms.txt`
routes.
- Regenerated `vercel.json` without redirect chains.
## Validation
- Documentation build passed.
- Scoped Remark and Vale linting passed.
- Playground linting passed.
- Redirect-chain checks passed.
- Full prose linting reports four existing Vale errors in unchanged
pages.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
- consolidate the Editor docs into one task-focused overview page
- move prompt block, tool configuration, and versioning details into
focused Reference pages
- explain database and code storage with concrete configurations and
generated JSON examples
- update navigation, inbound links, and redirects for the removed Prompt
and Tools pages
- correct Editor API, tool provider, versioning, and request-context
details against the implementation
## Validation
- `pnpm validate`
- `pnpm format:mdx:check`
- `pnpm lint:remark`
- targeted Vale checks for changed Editor pages
- `pnpm build`
- `git diff --check`
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR makes the Editor documentation easier to use. It puts common
guidance on one overview page and moves detailed prompt, tool, and
versioning information into focused reference pages.
## Changes
- Replaced the Editor overview with a task-focused guide covering:
- Studio workflows
- Prompt blocks
- Tools and MCP clients
- Permissions
- Database and repository storage
- Version selection
- Programmatic access
- Added Editor reference pages for:
- Prompt blocks
- Tool configuration
- Versioning
- Expanded tool provider documentation for Composio and Arcade.
- Documented Editor storage configuration, including the `editor` option
in `MastraCompositeStore`.
- Updated API, versioning, request-context, storage, and tool provider
details to match the implementation.
- Removed the separate Prompt and Tools pages.
- Updated sidebars, inbound links, playground links, and redirects for
the removed pages.
- Added examples for `codePath`, `MastraCompositeStore`, Composio,
Arcade, REST draft creation, and agent namespaces.
## Validation
- `pnpm validate`
- MDX formatting and Remark lint checks
- Targeted Vale checks
- `pnpm build`
- `git diff --check`
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
- reorganize the Get Started flow around creating, developing, and
structuring a Mastra project
- expand the Develop guide with Studio, AI-assisted development, project
structure, and file-based agents
- move Manual Install into Guides and Build with AI into Reference
- update links, sidebars, feature versioning, and direct redirects for
moved or removed pages
## Scope
This is a content-only change. It does not modify documentation
components, theme code, validation scripts, or tests.
Redirects were regenerated and audited for duplicate sources,
self-redirects, cycles, and redirect chains.
## Testing
- `pnpm validate`
- `pnpm lint:remark`
- Vale on every changed documentation file
- `pnpm build`
- `pnpm test:navigation`
- `pnpm test:smoke`
- `pnpm test:og`
The full local `pnpm lint:prose` command still reports four pre-existing
findings in unrelated files; the PR-scoped CI docs lint passes.
---------
Co-authored-by: Lennart <lekoarts@gmail.com>