## 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>
## Summary
PR 1 of 3 from the `auth-rbac-cms` branch split. This PR adds all
backend plumbing for auth/RBAC. PRs 2 (auth providers) and 3 (playground
UI) depend on this and can land in parallel once this merges.
- **New `@mastra/core/auth` export** — interfaces for RBAC, sessions,
SSO, credentials, ACL, and user management, plus default implementations
(static RBAC provider, cookie/memory session providers, built-in roles)
- **Server auth handlers** — login, signup, logout, session management,
and SSO flows with Zod-validated schemas
- **Route-level permission enforcement** — `requiresPermission` on route
configs with convention-based derivation from path/method (e.g. `GET
/agents/:id` → `agents:read`)
- **Server adapter RBAC middleware** (Hono, Express, Fastify, Koa) —
resolves user permissions via RBAC provider, cookie auth fallthrough for
session-based auth
- **Authorization policy fix** — `isProtectedPath` now uses
`isProtectedCustomRoute` instead of `!isCustomRoutePublic`, fixing a bug
where studio UI couldn't load in production
- **Deployer updates** — `MASTRA_PACKAGES_FILE` env var injection,
dynamic CORS origin when auth configured
- **Client SDK** — `getFullUrl` helper, `AuthCapabilities` type export
### Key behavioral changes
| Change | Risk | Mitigation |
|---|---|---|
| `SimpleAuth<TUser>` → `SimpleAuth<TUser extends EEUser>` | Medium —
requires `id` + `email` fields | Intentional; compile-time catch |
| `isProtectedPath` logic change | Medium — authorization policy | New
tests cover this; required for studio login in prod |
| Cookie fallthrough in Hono auth middleware | Low | Falls back to 401
if no user found |
| No RBAC → authenticated users get full access | Low — intentional |
Auth-only mode preserved |
| CORS dynamic origin when auth configured | Low | Only activates with
auth config; user can override |
### Deviation from plan
`deployers/cloud/package.json` — the plan called for adding
`@mastra/auth-cloud` dependency, but that package is created in PR 2.
Omitted here to avoid workspace resolution failure; PR 2 will add it.
### Fixed pre-existing test bug
All 4 adapter RBAC tests had a failing test ("should derive permissions
from route path/method when not explicitly set") that registered an API
handler at `/agents/test` with no prefix. That's a frontend/SPA path —
real API handlers are always under `/api/*`. Fixed the test to use
`prefix: '/api'` so the route is at `/api/agents/test`, matching how
routes are actually registered. Verified the bug exists on
`auth-rbac-cms` with clean install + build.
## Test plan
- [x] `pnpm build:packages` — 35/35 tasks pass
- [x] Core auth tests (cookie.test.ts) — 16/16 pass
- [x] Server tests (permissions, helpers, system) — 177/177 pass
- [x] Hono RBAC tests — 21/21 pass
- [x] Express RBAC tests — 15/15 pass
- [x] Fastify RBAC tests — 15/15 pass
- [x] Koa RBAC tests — 15/15 pass
- [x] Client SDK tests (base.test.ts) — 5/5 pass
- [ ] Verify no auth configured → all existing behavior identical (no
403s, no auth prompts)
- [ ] Verify pre-commit hooks pass (eslint + prettier)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Enterprise auth: SSO and credentials sign-in/sign-up, login/logout,
cookie and in-memory sessions, auth capabilities and current-user
endpoints.
* RBAC: default roles, static RBAC provider, route-level permission
enforcement and middleware across adapters.
* Client: full-URL helper; system responses include isDev.
* Deploy/build: bundling emits package metadata; deployers set runtime
packages file and adjust CORS when auth is enabled.
* **Bug Fixes**
* Studio UI loads correctly in production.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Shane Thomas <shane@codekarate.com>
Co-authored-by: Mastra Code (anthropic/claude-opus-4-6) <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>
## Description
<!-- Provide a brief description of the changes in this PR -->
## 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)
- [ ] 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**
* Updated Twitter Follow badge URL in README to reflect the current
social media handle.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Description
This details a significant capability of Mastra that wasn't listed in
the Readme
## 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**
* Updated README with information about MCP servers and their
capabilities.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Description
<!-- Provide a brief description of the changes in this PR -->
## 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)
- [ 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**
* Updated product branding and introductory documentation.
* Comprehensive migration guide to modernized APIs featuring enhanced
consistency, improved type safety, and better modularity across agents,
workflows, storage, and observability.
* **Chores**
* Added release metadata for upcoming patch.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Description
With our recent improvements to the docs, I'm copying some of that over
to some key README files.
## 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)
- [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
## Description
<!-- Provide a brief description of the changes in this PR -->
Readme updates to show how to add @mastra/mcp-docs-server to Claude Code
## 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)
- [x] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update
## Checklist
- [x] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works (N/A)
## Description
Added instructions to the readme for vulnerability reporting
## 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
---------
Co-authored-by: Allie Howe <allie@secvendors.cmo>
Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com>
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
## Description
Diff feature for the docs
Use `[!code ++]` and `[!code --]` to mark added and removed lines.
Example Usage:
<img width="653" height="268" alt="image"
src="https://github.com/user-attachments/assets/d3307fe3-548e-4a62-8943-d5f3a17b8474"
/>
Docs Preview:
<img width="1328" height="526" alt="CleanShot 2025-07-14 at 17 47 48@2x"
src="https://github.com/user-attachments/assets/c85fac17-ea8d-4b34-b722-622e1f89d816"
/>
## 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
---------
Co-authored-by: Paul Scanlon <pauliescanlon@gmail.com>
Co-authored-by: wardpeet <ward@coding-tech.com>
## Description
This fixes a small typo in the readme.md file 😅
## 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)
- [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
## Description
<!-- Provide a brief description of the changes in this PR -->
This PR fixes an issue with PG where camelCase names (as well as any
indexName that contained uppercase letters) weren't being saved
properly. The indexNames were not being quoted, so the case of the index
names were not being preserved. This PR changes this to quote the table
and schema names to allow for different cases.
## 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
## Description
Add MCP server info to the main documentation.
It was buried on this page https://mastra.ai/blog/introducing-mastra-mcp
under a link to this node package @mastra/mcp-docs-server which is very
non-obvious to find.
Since this is drastically going to improve our experience with Mastra,
it should be on the homepage.
## 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)
- [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
---------
Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com>
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
## Description
<!-- Provide a brief description of the changes in this PR -->
## 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
## Description
<!-- Provide a brief description of the changes in this PR -->
## 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
Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com>
## Description
<!-- Provide a brief description of the changes in this PR -->
## 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
## Description
More and more redirects regarding 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 performed a self-review of my own code
- [ ] 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
- [ ] New and existing unit tests pass locally with my changes
- [ ] I have generated a changeset for this PR
## Description
make download and package point to `mastra/core`
<!-- Provide a brief description of the changes in this PR -->
## 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)
- [x] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update
## Checklist
- [x] I have performed a self-review of my own code
- [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
- [ ] New and existing unit tests pass locally with my changes
- [ ] I have generated a changeset for this PR
## Description
Add relevant github badges.
This include
1. npm package
2. Github stars
3. Discord online users
4. Follow mastra_ai on X
5. Downloads per month
## 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)
- [x] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update
## Checklist
- [x] I have performed a self-review of my own code
- [ ] 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
- [ ] New and existing unit tests pass locally with my changes
- [ ] I have generated a changeset for this PR
## Description
This PR removes references to old docs with prefixed numbers. These docs
redirect to the correct pages, but this handles scubbing them
completely.
## 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 performed a self-review of my own code
- [ ] 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
- [ ] New and existing unit tests pass locally with my changes
- [ ] I have generated a changeset for this PR
Now that you can't import most things from "@mastra/core" we need to
update all our internal + example imports
---------
Co-authored-by: tyler barnes <tylerbarnes@Mac.lan>