Replaces the static workflow JPGs with Mermaid diagrams across the
suspend and resume, human-in-the-loop, and control flow pages. The
diagrams use the shared docs theme, include accessible titles and
descriptions, and remove the unused image assets. The pnpm workspace
policy marks Mermaid's transitive `@types/koa-compose` package as
non-building.
Closes#21771
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
The documentation now uses interactive Mermaid diagrams instead of
static workflow images. The diagrams support light and dark modes and
include accessibility information.
## Changes
- Replaced workflow JPG diagrams with Mermaid diagrams for:
- Suspend and resume
- Human-in-the-loop
- Sequential and parallel control flow
- Added shared Mermaid rendering with:
- Light and dark color palettes
- Semantic node and edge styles
- Responsive layout and overflow handling
- Error-boundary fallback
- Added accessible diagram titles and descriptions.
- Added Mermaid authoring guidance for documentation contributors.
- Added Mermaid support and dependencies to the Docusaurus site.
- Added Mermaid examples to the kitchen-sink page.
- Removed unused diagram image assets.
- Updated Docusaurus dependencies and workspace build configuration.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Description
Harness sidebar entries (Durable Agents, Goals, Schedules, Signals,
Signal Providers, Agent Controller, plus their
`AgentController`/`Signals` reference entries) no longer carry a `beta`
badge. Every other `tags: ['beta']` sidebar entry in
docs/guides/reference is now `tags: ['new']`.
Since the badge no longer conveys beta status, pages that had no beta
admonition got one (`:::experimental`, which renders as a "beta"
callout):
-
`reference/signals/{create-notification-inbox-tool,signal-provider,task-signal-provider,webhook-signal-provider}.mdx`
- `reference/tools/create-code-mode.mdx`
- `docs/server/auth/workers.mdx`, `guides/deployment/mastra-workers.mdx`
All other affected pages already had a beta admonition stating the API
may change (Trace Intelligence keeps its "Private beta" warning).
Interpretation note: harness-related reference entries were treated as
part of Harness, so their badges were removed rather than switched to
New.
Heads up: `pnpm validate` enforces a 30-day window on `new` tags, so
these badges will need removing (or refreshing) within a month.
`pnpm validate` passes.
## Related issue(s)
Requested in Slack:
https://kepler-bej6556.slack.com/archives/C0AV0VBFM0V/p1786355508067289?thread_ts=1786355508.067289&cid=C0AV0VBFM0V
## Type of change
- [x] Documentation update
## Checklist
- [x] I have made corresponding changes to the documentation (if
applicable)
Link to Devin session:
https://app.devin.ai/sessions/b8173ef4fa944cfea51b2fcd708e745a
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This update makes documentation labels more accurate. It marks beta
features with clear notices and labels newer features as `new`.
## Changes
- Removed incorrect `beta` labels from Harness entries.
- Changed remaining `beta` labels in `docs/guides/reference` to `new`.
- Added `:::experimental` callouts to affected documentation pages.
- Kept existing beta warnings unchanged, including Trace Intelligence’s
“Private beta” warning.
- Added untagged sidebar entries for Schedules, Signals, Signal
Providers, and Agent Controller.
- Confirmed that `pnpm validate` passes.
<!-- 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>
Co-authored-by: Alex Booker <booker@booker.codes>
## Description
Two related changes to docs sidebar labels and admonition styling:
**Sidebar labels (commit 1):**
- Removed the "Experimental" badge type entirely from the docs sidebar
- Changed Response Caching from `experimental` → `alpha` tag
- Reordered Agents section so Alpha items sit at the bottom, only above
Deprecated
- Removed unused `isExperimental` prop from playground-ui's `NavLink`
**Experimental admonition type (commit 2):**
- Added custom `experimental` admonition type with purple styling
(matching the Alpha sidebar pill)
- Swapped `tip` admonition color from purple → yellow
- Updated `signals.mdx` to use `:::experimental` instead of `:::warning
Experimental`
- Added `:::experimental` admonition to `response-caching.mdx` with
alpha disclaimer text
- Registered `experimental` keyword in all docs plugin configs
(`docusaurus.config.ts`)
## Related issue(s)
Requested by @AlexBooker in Slack.
## Type of change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test 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
- [x] I have addressed all Coderabbit comments on this PR\n"}
</invoke>
Link to Devin session:
https://app.devin.ai/sessions/4ca5c92dc70d40d2b69abf9a509baca0
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR replaces the docs' old "Experimental" sidebar badge/tooltip with
an Alpha label for affected pages, and introduces a proper
"experimental" admonition type (purple) so docs callouts about
alpha/experimental features display the correct title and styling.
## Changes
### High-level
- Remove the "Experimental" sidebar badge variant and the navigation
`isExperimental` flag/tooltip.
- Mark Response Caching (and Signals) as Alpha in the sidebar and
reorder Agents so Alpha items sit directly above Deprecated items.
- Add a dedicated `experimental` admonition type with purple styling and
ensure Docusaurus uses the correct default title for it.
- Register the `experimental` admonition keyword across docs plugin
configurations.
- Change `tip` admonition color from purple to yellow.
- Update docs to use `:::experimental` admonitions where appropriate
(signals, response-caching).
### Files & key edits
- docs/src/components/SidebarBadge.module.css
- Removed `.badge--experimental` (and dark-theme overrides); other badge
variants remain (a `.badge--deprecated` variant was added/adjusted).
- docs/src/components/SidebarBadge.tsx
- Removed `'experimental'` from the `BadgeType` union; handled types are
now 'new' | 'advanced' | 'beta' | 'alpha' | 'deprecated'.
- docs/src/theme/DocSidebarItem/utils.ts
- `getBadgeType` no longer recognizes `experimental`; falls back to
existing badge mappings (deprecated/new/beta/advanced/alpha).
- docs/src/content/en/docs/sidebars.js
- Added agents/adding-voice ("Voice").
- Changed `agents/response-caching` tags from `['experimental']` →
`['alpha']`.
- Reordered Agents so Alpha-tagged items appear directly above
Deprecated entries.
-
packages/playground-ui/src/ds/components/MainSidebar/main-sidebar-nav-link.tsx
- Removed `isExperimental?: boolean` prop and the "Experimental Feature"
tooltip (and CircleAlertIcon usage); minor import adjustments.
- docs/docusaurus.config.ts
- Introduced/used an ADMONITIONS_CONFIG (includes `experimental`) and
wired it into docs plugin/preset `admonitions` configs.
- docs/src/theme/Admonition/Layout/index.tsx
- Added styling mapping and icon for `experimental`; changed `tip`
styling to yellow; layout wired to render titles appropriately.
- docs/src/theme/Admonition/Type/Experimental.tsx
- New component providing default props (icon: true, title:
'experimental') forwarded to AdmonitionLayout.
- docs/src/theme/Admonition/Types.tsx
- Extended admonition types to include `experimental:
AdmonitionTypeExperimental` (merged with default types).
- docs/src/content/en/docs/agents/response-caching.mdx
- Added an `:::experimental` admonition with alpha-disclaimer text.
- docs/src/content/en/docs/agents/signals.mdx
- Switched top callout to `:::experimental` and updated wording to
indicate alpha status.
## Impact and review notes
- Scope: documentation and docs-theme UI only, plus a small
playground-ui nav-link cleanup; no runtime APIs or feature flags were
altered.
- Reviewers should verify:
- `experimental` admonitions render the correct default title while
still honoring explicit custom titles.
- Agents sidebar ordering places Alpha-tagged items immediately above
Deprecated entries.
- Sidebar badge types and playground nav links no longer reference the
removed `experimental` variant/flag.
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/mastra-ai/mastra/pull/16739?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)
<!-- review_stack_entry_end -->
<!-- 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>
Co-authored-by: Damien Schneider <74979845+damien-schneider@users.noreply.github.com>
Reverts mastra-ai/mastra#13452
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Chores**
* Updated documentation site configuration by removing trailing slash
settings from Docusaurus and Vercel configs.
* **Refactor**
* Removed custom Tabs component in favor of default Docusaurus
implementation.
* Enhanced Server-Side Rendering compatibility for category navigation
links.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Description
Add a build plugin (that only runs during `docusaurus build`) that
generates `llms.txt` files alongside each docs page with the contents of
each page.
More open in options:
<img width="322" height="294" alt="image"
src="https://github.com/user-attachments/assets/7029101d-6cf6-40ad-8c26-3878e288256a"
/>
New footer with link to llms.txt file:
<img width="361" height="73" alt="image"
src="https://github.com/user-attachments/assets/9885606f-dbde-4763-bfd1-4b711b3945c0"
/>
## Related Issue(s)
<!-- Link to the issue(s) this PR addresses, using hashtag notation:
Fixes#123 -->
## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [X] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update
## Checklist
- [ ] 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
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Per-page and site root llms.txt files are now generated for easier LLM
integration.
* Reworked page actions: a compact "Copy / Open in" menu provides quick,
data-driven links to external AI assistants and a direct llms.txt link.
* **Documentation**
* Standardized internal cross-reference links across storage and
observability docs.
* Clarified observability guidance and related warnings in multiple
storage pages.
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Description
A first pass at removing tech debt from docs and enforcing consistent
styling through lint-staged and working prettier config.
## Related Issue(s)
<!-- Link to the issue(s) this PR addresses, using hashtag notation:
Fixes#123 -->
## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update
## Checklist
- [ ] 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
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Removed the standalone Examples section and its sidebar
* Renamed "Adding Voice to Agents" to "Voice" and expanded the Next
Steps links
* Removed individual voice example pages and the Inngest workflow
example
* Removed the Examples tab from navigation (desktop and mobile)
* Added redirects from removed example routes to GitHub and core docs
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Description
Clean up cookie consent logic in the docs.
## Related Issue(s)
<!-- Link to the issue(s) this PR addresses, using hashtag notation:
#123 -->
## Type of Change
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update
## Checklist
- [ ] 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
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Refactor**
* Modernized site configuration to use TypeScript-typed config for
clearer, safer handling and cleaner plugin/output behavior.
* Reworked cookie-consent component logic to use explicit derived
consent flags, simplifying when analytics and marketing scripts render.
* **Bug Fixes / Behavior**
* Banner now auto-hides for non‑EU users and grants consent path
automatically, removing legacy stored-consent handling.
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->