feat: embedded documentation for AI coding agents #11472
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This proposal outlines a strategy to embed documentation inside published npm packages so coding agents can understand and use Mastra effectively. Key ideas: - Per-package docs/ folder with topic-organized content - SOURCE_MAP.json for machine-readable code navigation - Links to .d.ts (types) and .js (implementation) files - Generated from existing MDX documentation The goal is to enable AI coding agents to write Mastra code as if they were the framework creators, with full access to version-matched docs and readable source code.
🦋 Changeset detectedLatest commit: be73428 The changes in this PR will be included in the next version bump. This PR includes changesets to release 70 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Important Review skippedToo many files! 133 files out of 283 files are above the max files limit of 150. You can disable this status message by setting the WalkthroughThis PR introduces a comprehensive embedded documentation generation system for the Mastra monorepo. It adds tooling to generate machine-readable documentation (SKILL.md, SOURCE_MAP.json) from MDX source files and package exports, enabling documentation to be embedded within published npm packages for use in AI tools and MCP integrations. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~90 minutes The script Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
🚨 Redirect Validation FailedThe redirect validation found issues in Action Required: Review and fix the redirect configuration. |
- Add Claude Skills support via SKILL.md (Anthropic spec) - Add MCP tools for @mastra/mcp-docs-server enhancement - Remove vendor-specific approaches (universal only) - Add architecture diagram showing Skills + MCP integration - Update implementation plan with Skills and MCP phases - Add progressive disclosure explanation - Reference Anthropic Skills documentation
- Add scripts/generate-package-docs.ts that: - Analyzes dist/ to build SOURCE_MAP.json with 215 exports - Generates SKILL.md with Anthropic-compatible YAML frontmatter - Transforms MDX docs to clean Markdown - Adds code links to types and implementation files - Generate embedded docs: - SKILL.md - Claude Skills entry point - README.md - Navigation index - SOURCE_MAP.json - Machine-readable export map - agents/*.md - 7 agent topic docs - tools/*.md - 2 tool topic docs - workflows/*.md - 4 workflow topic docs - streaming/*.md - 2 streaming topic docs - Update package.json: - Add 'docs' to files array for npm publish - Add generate:docs script This completes Phase 1 items 1-4 of the embedded docs proposal.
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Loop until no more <!-- patterns remain to prevent incomplete sanitization that could leave malformed HTML fragments.
- Move script to scripts/generate-package-docs.ts (shared across packages) - Add docs.config.json for @mastra/core with 8 topics - Auto-discover code references from MDX imports/usage - Protect code blocks during MDX transformation - Fix PropertiesTable and JSX expression handling - Add mastra, server, observability, processors topics - Generate 44 markdown files across all topics
- Add postbuild script to generate docs to dist/docs/ - Remove committed generated docs (now generated at build time) - Add EMBEDDED_DOCS.md guide for adding docs to other packages - Update turbo.json with generate:docs task - Update package.json files array to include docs folder
TheIsrael1
added a commit
that referenced
this pull request
Jan 2, 2026
Adds 5 new MCP tools to read embedded documentation from installed @mastra/* packages: - listInstalledMastraPackages: Discover packages with embedded docs - readMastraSourceMap: Read export mappings from SOURCE_MAP.json - findMastraExport: Get type definitions and implementation for specific exports - readMastraEmbeddedDocs: Read topic documentation - searchMastraEmbeddedDocs: Search across all embedded docs These tools enable AI coding agents to understand Mastra packages by reading documentation directly from node_modules, complementing the embedded docs infrastructure merged in #11472. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
anowardear062-svg
approved these changes
Jan 6, 2026
|
Thanks for the update |
astout55555
pushed a commit
to astout55555/mastra
that referenced
this pull request
Jan 6, 2026
## 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: mastra-ai#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 -->
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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 sourcesSOURCE_MAP.json- Machine-readable index mapping exports → types → implementation (with line numbers)SKILL.md- Claude Skills entry point for automatic discoveryEMBEDDED_DOCS.md- Guide for adding embedded docs to any packagePackage Coverage (47 packages)
Each package gets:
docs.config.json- Topic/source file mappingspostbuildscript - Auto-generatesdist/docs/after buildHow It Works
dist/docs/on every buildExample 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
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.