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 -->
Adds a CI check that fails when any AGENTS.md file goes over the 500
token limit, then trims the existing AGENTS files so the repo passes the
new rule.
Before:
```md
# AGENTS.md
## Scope
This file applies to work in `packages/auth/`.
- Build from root: `pnpm build:auth`
```
After:
```md
Build from root: pnpm build:auth
Test from root: pnpm --filter ./packages/auth test
For broader auth coverage use pnpm test:auth
```
For codemod, the short AGENTS file now keeps the high-signal
instructions and points to a package-local skill for the longer workflow
and pattern reference.
codemod file went from ~5k tokens to 250, root AGENTS.md went from 1.8k
to 375
<img width="634" height="440" alt="Screenshot 2026-04-16 at 5 02 38 PM"
src="https://github.com/user-attachments/assets/307b6516-736b-47eb-98f4-48310d2d7d96"
/>
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR adds an automatic check that makes sure every AGENTS.md file
stays short (under 500 tokens) and shortens the existing AGENTS.md files
so they all pass that check.
## Overview
Enforces a 500-token limit for AGENTS.md files via CI, adds a validation
script to count tokens, and trims many AGENTS.md documents to keep only
high-signal guidance while moving large, detailed reference content into
a separate skill file.
## Changes
### CI & Validation
- Added `.github/scripts/validate-agents-md.mjs`: Node script that finds
AGENTS.md files, counts tokens using `tokenx`, and exits non‑zero if any
file exceeds the 500-token limit.
- Updated `.github/workflows/lint.yml`: new `agents-md-check` job runs
the validation script in CI for the mastra-ai/mastra repository.
### Dependencies
- Added `tokenx` (^1.3.0) to root `package.json` for token counting.
### AGENTS.md Consolidation
Multiple AGENTS.md files were condensed by removing multi-section
structure and extraneous formatting, preserving core commands and
high-signal instructions so each file stays ≤ 500 tokens:
- Root AGENTS.md: ~1.8k → 375 tokens (condensed conventions, removed
detailed examples and lengthy rules)
- docs/AGENTS.md: condensed docs and E2E guidance (removed fenced code
blocks and verbose explanations)
- packages/auth/AGENTS.md: simplified to core build/test guidance (62
tokens)
- packages/cli/AGENTS.md: collapsed into concise command lines (53
tokens)
- packages/codemod/AGENTS.md: main codemod guidance trimmed and
redirected to new skill file (result much smaller; AGENTS.md reduced
significantly)
- packages/core/AGENTS.md: flattened while keeping build/test/Zod-compat
notes (147 tokens)
- packages/mcp/AGENTS.md: consolidated client/server/integration test
guidance (107 tokens)
- packages/memory/AGENTS.md: reorganized integration workflow into a
concise section (283 tokens)
- packages/playground-ui/AGENTS.md: reduced to operational commands and
a brief design-system note (74 tokens)
- packages/playground/AGENTS.md: simplified build/test instructions and
coordination note (99 tokens)
- packages/rag/AGENTS.md: collapsed into brief build/test/lint guidance
(81 tokens)
- packages/server/AGENTS.md: condensed to three sentences covering
build/test/permissions (85 tokens)
### Knowledge Base Enhancement
- Added `packages/codemod/.claude/skills/codemod-patterns/SKILL.md`: a
607-line detailed codemod patterns and workflow guide moved out of
AGENTS.md to keep AGENTS.md concise.
## Validation
A terminal validation run (included in the PR) shows all AGENTS.md files
pass the 500-token rule, with token counts ranging from 53 to 403 and a
final message: "All AGENTS.md files are within the 500-token limit."
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Mastra Code (openai/gpt-5.4) <noreply@mastra.ai>
Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com>
## Description
- Add docs styleguides
- Add AGENTS.md files and point CLAUDE.md file to it
- Add mastra-docs claude skill
- Improve prompts on writing docs
## Related Issue(s)
Fixes DEVED-110
## 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**
* Added comprehensive docs and styleguides (DOC, STYLEGUIDE, GUIDE_* ,
REFERENCE) and new AGENTS.md; reorganized docs content and contributor
workflow.
* Replaced extensive CLAUDE.md content with pointer to AGENTS.md;
cleared docs changelog and removed some legacy guideline files.
* Updated CLI/pr/changeset prompts and guidance to require multiple
changesets for multi-package changes and warn against very long
changesets.
* **Community**
* Updated Code of Conduct with expanded scope and clearer enforcement
guidance.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>