> 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>
## Description
- Remove 1.0 banner
- Update `/guides` index page to include the same cards as the getting
started page (trying out MDX partials)
## 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**
* Added a reusable "Start" cards section showcasing quickstart and
framework integration guides (Next.js, React, SvelteKit, Astro, Nuxt,
Express, Hono, Electron)
* Replaced scattered card markup with the centralized Start cards
section across getting-started and guides pages
* Updated introductory copy for guides
* **Chores**
* Removed a promotional banner from the main documentation layout
* Sidebar validation now ignores partial/fragment documentation files
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Description
Add "Build with AI" category and skills subpage
## 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**
* Added Skills documentation page and a new "Build with AI" guide
covering Skills, MCP Docs Server, embedded docs, and usage tips.
* **Documentation**
* Reorganized sidebar to surface "Build with AI" content and updated MCP
Docs Server and Workspace Skills pages.
* Minor content edits across quickstart, memory docs, and observational
anchors.
* **Chores**
* Added permanent redirect for MCP Docs Server and refined
pagination/footer styling for docs UI.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
## 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
## Description
Misc hotfixes for docs
## 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**
* Updated navigation links in search empty-state to correct
documentation paths.
* Updated migration guide reference link to point to new documentation
location.
* **Chores**
* Added validation tool to verify redirect configurations for
consistency and accuracy.
* Removed redundant self-referencing redirects to streamline redirect
configuration.
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
Enables Mastra packages to ship embedded documentation that AI coding
agents can read directly from `node_modules`. This allows agents to
understand the framework as if they were its creators.
## What's Included
### Infrastructure
- **`scripts/generate-package-docs.ts`** - Shared script to generate
docs from MDX sources
- **`SOURCE_MAP.json`** - Machine-readable index mapping exports → types
→ implementation (with line numbers)
- **`SKILL.md`** - Claude Skills entry point for automatic discovery
- **`EMBEDDED_DOCS.md`** - Guide for adding embedded docs to any package
### Package Coverage (47 packages)
- **Core:** memory, rag, evals, mcp, server, auth, deployer, cli,
client-js, loggers
- **Voice:** 13 providers (openai, deepgram, elevenlabs, etc.)
- **Stores:** 22 providers (pg, libsql, pinecone, etc.)
Each package gets:
- `docs.config.json` - Topic/source file mappings
- `postbuild` script - Auto-generates `dist/docs/` after build
## How It Works
1. MDX docs are transformed to clean Markdown (Docusaurus components
stripped, code blocks preserved)
2. Code references are auto-discovered from imports/usage and linked to
SOURCE_MAP
3. Docs are generated to `dist/docs/` on every build
4. Published to npm alongside the package
## Example Output
node_modules/@mastra/core/dist/docs/
├── SKILL.md # Agent entry point
├── README.md # Navigation
├── SOURCE_MAP.json # Export → file mappings
├── agents/
│ ├── 01-overview.md
│ └── ...
└── tools/
└── ...
## Related
- Follow-up PR for MCP tools: #11488
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Embedded package documentation is now automatically generated and
included in published npm packages, making documentation accessible
directly within package distributions and enabling integration with AI
tools and Claude Skills.
* **Documentation**
* Added comprehensive embedded documentation guide for generating and
integrating documentation from source files into package distributions.
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Adds automatic regeneration of `llms.txt` and `llms-full.txt` files to
the scheduled provider documentation workflow.
## Changes
- Renamed workflow from "Regenerate Provider Registry" to "Regenerate
Providers & Docs"
- Added step to regenerate llms.txt files after model docs generation
- Updated git diff check to include the llms.txt files
- Updated commit messages and logs to reflect broader scope
## Why
The llms.txt files were previously generated manually. Now they'll be
automatically regenerated every 6 hours along with the provider registry
and model documentation, keeping them up-to-date with the latest
content.
**Before:**
```yaml
- name: Generate model documentation
run: pnpx tsx packages/core/scripts/generate-model-docs.ts
```
**After:**
```yaml
- name: Generate model documentation
run: pnpx tsx packages/core/scripts/generate-model-docs.ts
- name: Generate llms.txt files
run: pnpx tsx docs/scripts/build-llms-text-files.ts
```
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Chores**
* Updated workflow to regenerate providers and documentation together,
improving coordination of updates.
* Added automated generation of llms.txt documentation files.
* Enhanced change detection to include documentation files in the
workflow process.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
This removes Japanese content from the llms.txt generation script since
LLMs are multilingual and English documentation is sufficient.
The script was processing both English and Japanese directories,
resulting in very large files (llms.txt was 78k tokens, llms-full.txt
was 1.7M tokens).
Before:
```typescript
const enDir = path.join(contentDir, 'en');
const jaDir = path.join(contentDir, 'ja');
const enDocs = await processDirectory(enDir, 'en');
const jaDocs = await processDirectory(jaDir, 'ja');
const allDocs = [...enDocs, ...jaDocs];
```
After:
```typescript
const enDir = path.join(contentDir, 'en');
const enDocs = await processDirectory(enDir, 'en');
const allDocs = [...enDocs];
```
This should significantly reduce the file sizes while maintaining full
functionality since the English docs contain all the necessary
information for LLMs.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Chores
* Simplified documentation build process by consolidating to
English-only support, removing Japanese documentation processing to
streamline the build workflow.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Description
Migration of Nextra docs to Docusaurus.
## 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
* **Documentation**
* Removed a large set of docs in the docs-new directory, including
guides, examples, and reference pages across Agents, Auth, Deployment,
Examples, Evals, RAG, Memory, Observability, and Processors.
* **Chores**
* Updated redirect validation configuration source.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Paul Scanlon <pauliescanlon@gmail.com>
Co-authored-by: LekoArts <lekoarts@gmail.com>
## Description
Fix 404 error for certain docs page
## Related Issue(s)
## 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)
- [ ] I have added tests that prove my fix is effective or that my
feature works