## Summary
- Moved docs generation from build-time to pack-time using npm's
`prepack` lifecycle hook across all 46 packages that embed documentation
into their dist
- Removed the `build:docs` turbo task and `build:package-docs` root
script entirely
- Made `generate-package-docs.ts` exit gracefully when the docs manifest
is missing
No changeset required
## Motivation
The `build:docs` task in each package depends on `mastra-docs#build` (a
full Docusaurus site build), which in turn runs `git log` for the
sitemap plugin. This meant:
1. Every `pnpm build` required a git repository — builds failed outside
of git repos (in sandboxes)
2. Every package depending on `@mastra/core` transitively triggered a
full docs site build — e.g., `build:observability` pulled in the entire
Docusaurus build via `@mastra/core#build` → `build:docs` →
`mastra-docs#build`
3. Dev builds were slower than necessary — compiling docs that are only
needed at publish time
### What changed
* **`package.json` (46 files across packages/, stores/, voice/,
client-sdks/)**
Replaced `build:docs` (or `postbuild` in voice packages) with `prepack`,
so docs generation only runs during `npm pack`/`npm publish` — never
during regular builds.
Before (packages/stores):
```
"build:docs": "pnpx tsx ../../scripts/generate-package-docs.ts"
```
Before (voice packages):
```
"postbuild": "pnpx tsx ../../scripts/generate-package-docs.ts"
```
Before (CLI — embedded in build:lib):
```
"build:lib": "tsup --silent --config tsup.config.ts && pnpx tsx
../../scripts/generate-package-docs.ts"
```
After (all packages):
```
"prepack": "pnpx tsx ../../scripts/generate-package-docs.ts"
```
* **`turbo.json` (34 files — root + 33 packages)**
Removed the `build:docs` task definition entirely. It's no longer a
turbo task — docs generation is handled by the npm `prepack` lifecycle
instead.
* **`package.json` (root)**
Removed:
```
"build:package-docs": "pnpm turbo run build:docs"
```
* **`.github/workflows/npm-publish.yml`**
Removed all `pnpm build:package-docs` steps from prerelease, stable, and
exit-prerelease-mode flows. No longer needed — `prepack` fires
automatically during `pnpm publish -r`.
* **`scripts/generate-package-docs.ts`**
Changed error handling to exit gracefully (warn instead of crash) when
`docs/build/llms-manifest.json` is missing. This ensures `prepack`
doesn't block packaging when the docs site hasn't been built (e.g.,
local development, snapshots).
## Test plan
- Verify `pnpm build` succeeds without triggering docs generation
- Verify `pnpm pack` in a package with the docs site built generates
embedded docs via `prepack`
- Verify `pnpm pack` without the docs site built warns but doesn't fail
- Verify CI publish workflows still produce packages with embedded docs
(prepack fires during `pnpm publish -r`)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Chores**
* Docs generation now runs automatically during package preparation
(prepack) instead of as part of the main build.
* Removed separate docs build tasks to simplify and streamline build
dependency graphs across packages.
* **Bug Fixes**
* Improved docs generator error handling: failures fail CI but surface
as warnings locally to avoid blocking development.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
This PR reorganizes the test infrastructure across the monorepo by
introducing namespaced Vitest projects, proper test classification, and
a dedicated e2e CI job.
### Vitest project namespacing
- Rename all vitest project names from generic `'unit'` to
`'unit:<package-path>'` (e.g. `'unit:packages/core'`,
`'unit:auth/auth0'`) across ~100 packages
- Enables targeted test filtering with `--project 'unit:*'` glob
patterns in CI and locally
- Update CI workflow to use `'unit:*'` and `'typecheck:*'` patterns
### Test classification
- **Store tests** → `e2e:stores/*` (require external services like
Postgres, Redis, etc.)
- **RAG tests** → `e2e:packages/rag` (require embeddings API)
- **Evals LLM scorer tests** → `e2e:packages/evals` (require LLM API
keys)
- **pubsub tests** → `e2e:pubsub/*` (require Google Cloud)
- Add `isolate: false` to unit test configs for faster execution
### Core test reorganization
Split `agent.test.ts` (~7.5k lines) into focused unit test modules:
- `callbacks.test.ts` — callback/hook behavior
- `input-processors.test.ts` — input processing logic
- `instructions.test.ts` — instruction/system prompt handling
- `memory-metadata.test.ts` — memory metadata tests
- `save-and-errors.test.ts` — save behavior and error handling
- `title-generation.test.ts` — title generation logic
Renamed integration tests to `*.e2e.test.ts` for clarity (e.g.
`azure.integration.test.ts` → `azure.e2e.test.ts`).
### CI changes
- Add dedicated `e2e-test` job in `vitest-changed.yml` with shard-based
matrix
- Normalize shard names (`/` → `-`) for GitHub artifact compatibility
- Wire e2e job into `merge-reports` dependency chain
### Test fixes
- `tsx` → `tsx@latest` in MCP spawn calls to fix version resolution
- Rewrite `deployers/cloud` mock patterns for test reliability
- Skip network-dependent `mcp-registry-registry` tests (apitracker,
mcprun)
- Fix codemod `typeParameters` compatibility check
- Add `cwd` to CLI execa call
### Test plan
- Verified `pnpm vitest run --project 'unit:*'` runs only unit tests
- Verified `pnpm vitest run --project 'e2e:*'` runs only e2e tests
- Verified all extracted agent test files pass independently
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Tests**
* Added comprehensive test suites for agent features including
callbacks, input processors, instructions, memory handling, and title
generation across v1 and v2 implementations
* Reorganized test infrastructure with dedicated end-to-end test
workflows separate from unit tests
* Enhanced test isolation and parallel execution with named test
projects
* **Chores**
* Restructured test configuration across all packages for improved
organization and execution
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Mastra Code <noreply@mastra.ai>
## Description
Improve the `generate-package-docs.ts` script by using the new
`llms-manifest.json` from docs to copy over llms.txt files to the
embedded docs (previously the raw MDX was parsed and assembled).
This PR also updates the script to be run without any cli args, it just
runs in the current `process.cwd()` context. This simplifies usage when
running via `npm` scripts. This PR also improves the performance of the
`SOURCE_MAP.json` generation by 2x.
Lastly, the `dist/docs` structure itself is updated to follow the agent
skills spec.
## 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
- [X] 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**
* Docs generation moved to a centralized, manifest-driven workflow;
package-level doc scripts simplified to rely on contextual discovery and
a central docs build.
* Build tasks updated across packages to depend on the centralized docs
build step.
* **Documentation**
* Replaced a lengthy proposal with a concise Turbo-focused guide and
added optional description metadata for doc entries.
* **Bug Fix**
* Removed noisy console warnings during docs site initialization.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and publish to npm
yourself or [setup this action to publish
automatically](https://github.com/changesets/action#with-publishing). If
you're not ready to do a release yet, that's fine, whenever you add more
changesets to main, this PR will be updated.
⚠️⚠️⚠️⚠️⚠️⚠️
`main` is currently in **pre mode** so this branch has prereleases
rather than normal releases. If you want to exit prereleases, run
`changeset pre exit` on `main`.
⚠️⚠️⚠️⚠️⚠️⚠️
# Releases
> The changelog information of each package has been omitted from this
message, as the content exceeds the size limit.
## @mastra/client-js@1.0.0-beta.20
## @mastra/braintrust@1.0.0-beta.11
## @mastra/observability@1.0.0-beta.10
## @mastra/core@1.0.0-beta.20
## @mastra/rag@2.0.0-beta.5
## @mastra/server@1.0.0-beta.20
## @mastra/express@0.1.0-beta.15
## @mastra/fastify@0.1.0-beta.15
## @mastra/hono@0.1.0-beta.15
## @mastra/koa@0.1.0-beta.15
## @mastra/auth-clerk@1.0.0-beta.3
## @mastra/auth-workos@1.0.0-beta.2
## @mastra/ai-sdk@1.0.0-beta.13
## @mastra/react@0.1.0-beta.20
## @mastra/deployer-cloud@1.0.0-beta.20
## @mastra/deployer-cloudflare@1.0.0-beta.2
## @mastra/deployer-netlify@1.0.0-beta.3
## @mastra/deployer-vercel@1.0.0-beta.2
## @mastra/dane@1.0.0-beta.20
## @mastra/longmemeval@1.0.0-beta.20
## @mastra/arize@1.0.0-beta.11
## @mastra/langfuse@1.0.0-beta.10
## @mastra/langsmith@1.0.0-beta.11
## @mastra/otel-bridge@1.0.0-beta.10
## @mastra/otel-exporter@1.0.0-beta.11
## @mastra/posthog@1.0.0-beta.10
## @mastra/agent-builder@1.0.0-beta.11
## @mastra/auth@1.0.0-beta.2
## mastra@1.0.0-beta.13
## @mastra/codemod@0.1.0-beta.5
## create-mastra@1.0.0-beta.13
## @mastra/deployer@1.0.0-beta.20
## @mastra/evals@1.0.0-beta.4
## @mastra/fastembed@1.0.0-beta.3
## @mastra/loggers@1.0.0-beta.4
## @mastra/mcp@1.0.0-beta.8
## @mastra/mcp-docs-server@1.0.0-beta.20
## @mastra/memory@1.0.0-beta.11
## @mastra/playground-ui@7.0.0-beta.20
## @mastra/astra@1.0.0-beta.3
## @mastra/chroma@1.0.0-beta.4
## @mastra/clickhouse@1.0.0-beta.9
## @mastra/cloudflare@1.0.0-beta.10
## @mastra/cloudflare-d1@1.0.0-beta.9
## @mastra/convex@0.1.0-beta.8
## @mastra/couchbase@1.0.0-beta.4
## @mastra/duckdb@1.0.0-beta.3
## @mastra/dynamodb@1.0.0-beta.9
## @mastra/elasticsearch@1.0.0-beta.4
## @mastra/lance@1.0.0-beta.10
## @mastra/libsql@1.0.0-beta.11
## @mastra/mongodb@1.0.0-beta.10
## @mastra/mssql@1.0.0-beta.10
## @mastra/opensearch@1.0.0-beta.3
## @mastra/pg@1.0.0-beta.12
## @mastra/pinecone@1.0.0-beta.4
## @mastra/qdrant@1.0.0-beta.3
## @mastra/s3vectors@1.0.0-beta.3
## @mastra/turbopuffer@1.0.0-beta.3
## @mastra/upstash@1.0.0-beta.10
## @mastra/vectorize@1.0.0-beta.3
## @mastra/voice-azure@0.11.0-beta.1
## @mastra/voice-cloudflare@0.12.0-beta.1
## @mastra/voice-deepgram@0.12.0-beta.2
## @mastra/voice-elevenlabs@0.12.0-beta.2
## @mastra/voice-google@0.12.0-beta.2
## @mastra/voice-google-gemini-live@0.11.0-beta.3
## @mastra/voice-murf@0.12.0-beta.1
## @mastra/voice-openai@0.12.0-beta.2
## @mastra/voice-openai-realtime@0.12.0-beta.1
## @mastra/voice-playai@0.12.0-beta.1
## @mastra/voice-sarvam@0.12.0-beta.1
## @mastra/voice-speechify@0.12.0-beta.1
## @mastra/inngest@1.0.0-beta.11
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
## 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 -->