0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/scripts/generate-package-docs.ts

197 lines
6.6 KiB

feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
feat: embedded documentation for AI coding agents (#11472) ## 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 -->
2025-12-31 01:39:28 +01:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00
Decouple package docs generation from build task (#12836) ## 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 -->
2026-02-10 05:22:14 -08:00
chore(repo): Improve embedded docs script (#12664) ## 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 -->
2026-02-05 01:24:43 +01:00