@mastra/mcp-docs-server 1.2.17-alpha.7 → 1.2.17

package/.docs/integrations/deploy/kubernetes.md

@@ -4,9 +4,9 @@
 
 Run a Mastra application across multiple pods on [Kubernetes](https://kubernetes.io/), so it scales horizontally behind a load balancer. Because each pod is a separate process, the pods must share a pub/sub backend and a database, otherwise work started on one pod is invisible to the others.
 
-> **Note:** This guide covers deploying the [Mastra server](https://mastra.ai/docs/server/mastra-server). If you're using a [server adapter](https://mastra.ai/docs/server/server-adapters) or [web framework](https://mastra.ai/docs/deployment/web-framework), deploy the way you normally would for that framework.
+> **Note:** This guide covers deploying the [Mastra server](https://mastra.ai/docs/server/overview). If you're using a [server adapter](https://mastra.ai/docs/server/server-adapters) or [web framework](https://mastra.ai/docs/deployment/web-framework), deploy the way you normally would for that framework.
 
-> **Beta:** Multi-pod support relies on [durable agents](https://mastra.ai/docs/long-running-agents/durable-agents). Breaking changes may occur without a major version bump until the API is stable. Read [Known limitations](#known-limitations) before you rely on this in production.
+> **Beta:** Multi-pod support relies on [durable agents](https://mastra.ai/docs/harness/durable-agents). Breaking changes may occur without a major version bump until the API is stable. Read [Known limitations](#known-limitations) before you rely on this in production.
 
 ## Before you begin
 
@@ -25,7 +25,7 @@ A single pod keeps run state in its own memory. With one pod that's fine, becaus
 Redis and Postgres close that gap:
 
 - **Pub/sub** carries events between pods. When an event is published on one pod, the others receive it. Mastra uses [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams), which also provides the per-thread leasing that keeps a single pod as the owner of a conversation at a time. See [PubSub](https://mastra.ai/docs/server/pubsub).
-- **Storage** persists run state. [Durable agents](https://mastra.ai/docs/long-running-agents/durable-agents) save each run as a workflow snapshot, so any pod can resume a run from the database after a restart or when a request is routed elsewhere.
+- **Storage** persists run state. [Durable agents](https://mastra.ai/docs/harness/durable-agents) save each run as a workflow snapshot, so any pod can resume a run from the database after a restart or when a request is routed elsewhere.
 
 ## Configure shared infrastructure
 
@@ -87,7 +87,7 @@ The `cache` is what makes resumable streams work across pods. A reconnecting cli
 
 ## Use durable agents
 
-A plain [`Agent`](https://mastra.ai/docs/agents/overview) keeps its stream and approval state in one pod's memory, so those don't survive a request landing on another pod. A [durable agent](https://mastra.ai/docs/long-running-agents/durable-agents) runs the agentic loop inside a workflow and persists its state, so any pod can observe or resume the same run.
+A plain [`Agent`](https://mastra.ai/docs/agents/overview) keeps its stream and approval state in one pod's memory, so those don't survive a request landing on another pod. A [durable agent](https://mastra.ai/docs/harness/durable-agents) runs the agentic loop inside a workflow and persists its state, so any pod can observe or resume the same run.
 
 Wrap the agent with `createDurableAgent()`:
 
@@ -109,7 +109,7 @@ Register the durable agent with the `Mastra` instance above. Its run state now l
 
 ## Deploy
 
-1. Build and containerize the Mastra server, then push the image to your registry. Follow the [Mastra server](https://mastra.ai/docs/server/mastra-server) guide for the build, and ensure the server reads `process.env.PORT` and listens on `0.0.0.0`.
+1. Build and containerize the Mastra server, then push the image to your registry. Follow the [Mastra server](https://mastra.ai/docs/server/overview) guide for the build, and ensure the server reads `process.env.PORT` and listens on `0.0.0.0`.
 
 2. Store the shared connection strings as a Secret:
 
@@ -242,7 +242,7 @@ Register the durable agent with the `Mastra` instance above. Its run state now l
 
    A JSON list of your agents means the deployment is serving.
 
-   > **Warning:** Set up [authentication](https://mastra.ai/docs/server/auth) before exposing your endpoints publicly.
+   > **Warning:** Set up [authentication](https://mastra.ai/docs/auth/overview) before exposing your endpoints publicly.
 
 ## Streaming and reconnection
 
@@ -258,7 +258,7 @@ for await (const chunk of output.fullStream) {
 cleanup()
 ```
 
-Because the run state is in Postgres and the events are in Redis, the reconnecting request can be served by any pod, not only the one that started the run. See [Resumable streams](https://mastra.ai/docs/long-running-agents/durable-agents).
+Because the run state is in Postgres and the events are in Redis, the reconnecting request can be served by any pod, not only the one that started the run. See [Resumable streams](https://mastra.ai/docs/harness/durable-agents).
 
 Multiple clients can observe the same run at once. Each `observe()` call receives the full stream, so a user watching from two devices, or two people following the same run, stay in sync.
 
@@ -281,11 +281,11 @@ The run suspends before the tool runs. Approve it later, from any pod:
 await durableAssistant.resume(runId, { approved: true })
 ```
 
-The pod that handles the approval loads the suspended run from Postgres. It then runs the approved tool and publishes the result over the shared pub/sub, so a client observing the run receives the continuation. See [Tool approval](https://mastra.ai/docs/long-running-agents/durable-agents).
+The pod that handles the approval loads the suspended run from Postgres. It then runs the approved tool and publishes the result over the shared pub/sub, so a client observing the run receives the continuation. See [Tool approval](https://mastra.ai/docs/harness/durable-agents).
 
 ## Known limitations
 
-- The default in-process setup keeps run state in one pod's memory and doesn't share it across pods. Use [durable agents](https://mastra.ai/docs/long-running-agents/durable-agents) with shared Redis and Postgres so streaming, approvals, and reconnection work across pods.
+- The default in-process setup keeps run state in one pod's memory and doesn't share it across pods. Use [durable agents](https://mastra.ai/docs/harness/durable-agents) with shared Redis and Postgres so streaming, approvals, and reconnection work across pods.
 - Cross-pod streaming, approvals, and reconnection require the durable-agent path. A plain agent keeps run state in memory and doesn't resume on another pod.
 - When multiple pods start at once against an uninitialized database, they can race to create the schema and a pod may fail to start. Start with one replica so the schema is created once, then scale up.
 - For a stricter setup, initialize the schema outside the app (for example, a one-off Kubernetes Job) and set `disableInit: true` on the `PostgresStore` in every pod.
@@ -293,7 +293,7 @@ The pod that handles the approval loads the suspended run from Postgres. It then
 ## Related
 
 - [PubSub](https://mastra.ai/docs/server/pubsub)
-- [Durable agents](https://mastra.ai/docs/long-running-agents/durable-agents)
+- [Durable agents](https://mastra.ai/docs/harness/durable-agents)
 - [Workers](https://mastra.ai/docs/deployment/workers): Split background processing into separate containers on Kubernetes
-- [Mastra server](https://mastra.ai/docs/server/mastra-server)
+- [Mastra server](https://mastra.ai/docs/server/overview)
 - [Deployment overview](https://mastra.ai/docs/deployment/overview)

package/.docs/integrations/deploy/netlify.md

@@ -4,7 +4,7 @@
 
 Use `@mastra/deployer-netlify` to deploy your Mastra server on Netlify. The deployer bundles your code and generates a `.netlify` directory conforming to Netlify's [Frameworks API](https://docs.netlify.com/build/frameworks/frameworks-api/), ready to deploy. You can deploy as serverless functions (default) or as [edge functions](https://docs.netlify.com/build/edge-functions/overview/) for lower latency and longer execution times.
 
-> **Note:** This guide covers deploying the [Mastra server](https://mastra.ai/docs/server/mastra-server). If you're using a [server adapter](https://mastra.ai/docs/server/server-adapters) or [web framework](https://mastra.ai/docs/deployment/web-framework), deploy the way you normally would for that framework.
+> **Note:** This guide covers deploying the [Mastra server](https://mastra.ai/docs/server/overview). If you're using a [server adapter](https://mastra.ai/docs/server/server-adapters) or [web framework](https://mastra.ai/docs/deployment/web-framework), deploy the way you normally would for that framework.
 
 ## Before you begin
 
@@ -85,10 +85,10 @@ After setting up your project, push it to your remote Git provider of choice (e.
 
 3. Verify your deployment at `https://<random-slug>.netlify.app/api/agents`, which should return a JSON list of your agents.
 
-   Since the [Mastra server](https://mastra.ai/docs/server/mastra-server) prefixes every API endpoint with `/api`, you have to add it to your URLs when making requests.
+   Since the [Mastra server](https://mastra.ai/docs/server/overview) prefixes every API endpoint with `/api`, you have to add it to your URLs when making requests.
 
    > **Note:** Netlify functions are typically deployed at `https://<random-slug>.netlify.app/.netlify/functions/api`. The `NetlifyDeployer` redirects any request from `/*` to `/.netlify/functions/api/:splat`, so you don't need to include the `.netlify/functions` prefix in your URLs.
 
 4. You can now call your Mastra endpoints over HTTP.
 
-   > **Warning:** Set up [authentication](https://mastra.ai/docs/server/auth) before exposing your endpoints publicly.
+   > **Warning:** Set up [authentication](https://mastra.ai/docs/auth/overview) before exposing your endpoints publicly.

package/.docs/integrations/deploy/render.md

@@ -0,0 +1,389 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Render
+
+Deploy Mastra applications on [Render](https://render.com/). Host the Mastra API as a [web service](https://render.com/docs/web-services), or use [Render Workflows](https://render.com/docs/workflows) for long-running tasks with independent retry policies.
+
+Choose the deployment path that fits your application:
+
+- **Mastra API**: Deploy Mastra's [server](https://mastra.ai/docs/server/overview) as a web service with a public endpoint. The [Web Services guide](https://render.com/docs/web-services) explains how to deploy custom code or a supported [server adapter](https://mastra.ai/docs/server/server-adapters).
+- **Mastra workflow**: Run an entire Mastra workflow within one task. Render controls the outer run, while Mastra manages its steps and state. See [Defining Workflow Tasks](https://render.com/docs/workflows-defining) for configuration details.
+- **Distributed agent operations**: Give each operation its own compute plan, timeout, and retry policy. Render Workflows handles the execution queue and provides run observability.
+
+This guide builds an editorial pipeline that reviews a draft from three perspectives in parallel, then passes the feedback to an editor agent. Use the links above if you want to deploy a Mastra API or execute an entire Mastra workflow as one task.
+
+## How Render Workflows integrates with Mastra
+
+Mastra supplies the agents and application logic, while Render Workflows defines the execution boundaries. A typical pipeline has three layers:
+
+1. A parent task coordinates the run.
+2. Child tasks invoke Mastra agents for focused work.
+3. A final task combines the results.
+
+Calling one task from another creates a chained run in a separate instance, with its own compute plan, timeout, and retry policy.
+
+## Setup
+
+Create an empty Mastra project named `render-workflows`:
+
+**npm**:
+
+```bash
+npm create mastra@latest render-workflows -- --empty
+```
+
+**pnpm**:
+
+```bash
+pnpm create mastra render-workflows --empty
+```
+
+**Yarn**:
+
+```bash
+yarn create mastra render-workflows --empty
+```
+
+**Bun**:
+
+```bash
+bunx create-mastra render-workflows --empty
+```
+
+Install two additional dependencies:
+
+**npm**:
+
+```bash
+npm install @renderinc/sdk tsx
+```
+
+**pnpm**:
+
+```bash
+pnpm add @renderinc/sdk tsx
+```
+
+**Yarn**:
+
+```bash
+yarn add @renderinc/sdk tsx
+```
+
+**Bun**:
+
+```bash
+bun add @renderinc/sdk tsx
+```
+
+Add your API key to an `.env` file. This example uses OpenAI, but any supported [model provider](https://mastra.ai/models) works.
+
+```text
+OPENAI_API_KEY=your_openai_api_key
+```
+
+Install the [Render CLI](https://render.com/docs/cli) to run workflow commands from your terminal.
+
+## Distributed agent pipeline
+
+### Create the agents
+
+In `src/mastra`, create an `agents` directory with `reviewer-agent.ts` and `editor-agent.ts`. Define both agents:
+
+```ts
+import { Agent } from '@mastra/core/agent'
+
+export const reviewerAgent = new Agent({
+  id: 'reviewer-agent',
+  name: 'Reviewer Agent',
+  model: 'openai/gpt-5.6-sol',
+  instructions: `
+    Review the supplied draft only from the requested perspective.
+    Identify concrete problems and recommend specific changes.
+    Do not rewrite the full draft.
+  `,
+})
+```
+
+```ts
+import { Agent } from '@mastra/core/agent'
+
+export const editorAgent = new Agent({
+  id: 'editor-agent',
+  name: 'Editor Agent',
+  model: 'openai/gpt-5.6-sol',
+  instructions: `
+    Revise the supplied draft using the reviewers' feedback.
+    Return the complete revised draft and nothing else.
+    Preserve accurate details and do not introduce unsupported claims.
+  `,
+})
+```
+
+### Configure the Mastra instance
+
+Add both agents to the Mastra instance in `src/mastra/index.ts`:
+
+```ts
+import { Mastra } from '@mastra/core/mastra'
+import { editorAgent } from './agents/editor-agent.js'
+import { reviewerAgent } from './agents/reviewer-agent.js'
+
+export const mastra = new Mastra({
+  agents: {
+    editorAgent,
+    reviewerAgent,
+  },
+})
+```
+
+### Create the tasks
+
+In `src`, create a `tasks` directory with `review-task.ts`, `revision-task.ts`, and `editorial-task.ts`.
+
+#### Review task
+
+The reviewer agent handles one area of focus. Its compute plan, five-minute timeout, and retry policy apply only to that analysis. A temporary model-provider failure can trigger another attempt without restarting the other reviewers.
+
+```typescript
+import { task } from '@renderinc/sdk/workflows'
+import { mastra } from '../mastra/index.js'
+
+type Review = {
+  focus: string
+  feedback: string
+}
+
+export const reviewDraft = task(
+  {
+    name: 'review_draft',
+    plan: 'starter',
+    timeoutSeconds: 300,
+    retry: {
+      maxRetries: 2,
+      waitDurationMs: 1_000,
+      backoffScaling: 2,
+    },
+  },
+  async function reviewDraft(draft: string, focus: string): Promise<Review> {
+    const reviewer = mastra.getAgentById('reviewer-agent')
+    const response = await reviewer.generate(`
+      Review this draft for ${focus}.
+      Draft: ${draft}
+    `)
+    if (!response.text) {
+      throw new Error(`The ${focus} review returned no text`)
+    }
+    return {
+      focus,
+      feedback: response.text,
+    }
+  },
+)
+```
+
+#### Revision task
+
+This task combines the feedback and produces a revised draft. It uses a larger compute plan and a longer timeout than each reviewer.
+
+```typescript
+import { task } from '@renderinc/sdk/workflows'
+import { mastra } from '../mastra/index.js'
+
+type Review = {
+  focus: string
+  feedback: string
+}
+
+export const reviseDraft = task(
+  {
+    name: 'revise_draft',
+    plan: 'standard',
+    timeoutSeconds: 600,
+    retry: {
+      maxRetries: 2,
+      waitDurationMs: 1_000,
+      backoffScaling: 2,
+    },
+  },
+  async function reviseDraft(draft: string, reviews: Review[]): Promise<{ draft: string }> {
+    const editor = mastra.getAgentById('editor-agent')
+    const response = await editor.generate(`
+      Revise the draft using the review feedback.
+      Draft: ${draft}
+      Reviews: ${JSON.stringify(reviews, null, 2)}
+    `)
+    if (!response.text) {
+      throw new Error('The editor returned no text')
+    }
+    return {
+      draft: response.text,
+    }
+  },
+)
+```
+
+#### Editorial task
+
+The parent dispatches three reviews in parallel with `Promise.all()`, then sends their combined feedback to the revision step. Retries are disabled at this level because each child defines its own policy. If you enable orchestration retries, ensure that another attempt can't duplicate external side effects or other non-idempotent work.
+
+```typescript
+import { task } from '@renderinc/sdk/workflows'
+import { reviewDraft } from './review-task.js'
+import { reviseDraft } from './revision-task.js'
+
+export const editorialPipeline = task(
+  {
+    name: 'editorial_pipeline',
+    plan: 'starter',
+    timeoutSeconds: 1_200,
+    retry: {
+      maxRetries: 0,
+      waitDurationMs: 1_000,
+      backoffScaling: 2,
+    },
+  },
+  async function editorialPipeline(draft: string): Promise<{ draft: string }> {
+    const focuses = ['technical clarity', 'structure and flow', 'reader usefulness']
+    const reviews = await Promise.all(focuses.map(focus => reviewDraft(draft, focus)))
+    return reviseDraft(draft, reviews)
+  },
+)
+```
+
+### Set up the entry point
+
+Create `src/index.ts` and import the editorial task:
+
+```ts
+import './tasks/editorial-task.js'
+```
+
+In `package.json`, add scripts to build the TypeScript project and run the workflow:
+
+```json
+{
+  "scripts": {
+    "build": "tsc",
+    "dev:workflows": "tsx src/index.ts",
+    "start:workflows": "node dist/index.js"
+  }
+}
+```
+
+Configure `tsconfig.json` for the build:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "src",
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"]
+}
+```
+
+Build the project. The command compiles the JavaScript files into `dist`.
+
+**npm**:
+
+```bash
+npm run build
+```
+
+**pnpm**:
+
+```bash
+pnpm run build
+```
+
+**Yarn**:
+
+```bash
+yarn build
+```
+
+**Bun**:
+
+```bash
+bun run build
+```
+
+## Run the pipeline
+
+### Locally
+
+Start the local development server with the Render CLI:
+
+```bash
+render workflows dev -- npm run dev:workflows
+```
+
+The server lists the registered tasks:
+
+```bash
+➜ render workflows dev -- npm run dev:workflows
+Workflow server listening on port 8120
+Loaded environment variables from .env
+3 tasks found in npm run dev:workflows
+  • editorial_pipeline
+  • review_draft
+  • revise_draft
+
+To browse and run tasks, open another terminal and run:
+  render workflows tasks list --local
+```
+
+In another terminal, confirm that the tasks are available:
+
+```bash
+render workflows tasks list --local
+```
+
+The command displays each task's name, ID, and creation time. Press `Ctrl+C`, then start the editorial pipeline from the same terminal:
+
+```bash
+render workflows tasks runs start editorial_pipeline \
+  --local \
+  --input='["Render Workflows runs long-running tasks outside the request lifecycle."]'
+```
+
+The development server records the parent run, three parallel reviews, and the final revision.
+
+### Production
+
+Create a workflow service from the current repository:
+
+```bash
+render workflows create \
+  --name mastra-workflows \
+  --repo . \
+  --runtime node \
+  --build-command "npm install && npm run build" \
+  --run-command "npm run start:workflows"
+```
+
+Add `OPENAI_API_KEY`, or the key for your chosen model provider, to the service's environment variables.
+
+After deployment, start a production run. If needed, replace `mastra-workflows/editorial_pipeline` with the task slug shown in the Render Dashboard.
+
+```bash
+render workflows tasks start mastra-workflows/editorial_pipeline \
+  --input='["Render Workflows runs long-running tasks outside the request lifecycle."]'
+```
+
+Open the workflow service in the Render Dashboard to inspect each task run, attempt, result, and log stream.
+
+## Related
+
+- [Render Workflows documentation](https://render.com/docs/workflows)
+- [Defining Render workflow tasks](https://render.com/docs/workflows-defining)
+- [Triggering task runs](https://render.com/docs/workflows-running)
+- [Render Workflows TypeScript SDK](https://render.com/docs/workflows-sdk-typescript)
+- [Render Workflows limits and pricing](https://render.com/docs/workflows-limits)

package/.docs/integrations/deploy/vercel.md

@@ -4,7 +4,7 @@
 
 Use `@mastra/deployer-vercel` to deploy your Mastra server as serverless functions on Vercel. The deployer bundles your code and generates a `.vercel/output` directory conforming to Vercel's [Build Output API](https://vercel.com/docs/build-output-api/v3), ready to deploy with no additional configuration.
 
-> **Note:** This guide covers deploying the [Mastra server](https://mastra.ai/docs/server/mastra-server). If you're using a [server adapter](https://mastra.ai/docs/server/server-adapters) or [web framework](https://mastra.ai/docs/deployment/web-framework), deploy the way you normally would for that framework.
+> **Note:** This guide covers deploying the [Mastra server](https://mastra.ai/docs/server/overview). If you're using a [server adapter](https://mastra.ai/docs/server/server-adapters) or [web framework](https://mastra.ai/docs/deployment/web-framework), deploy the way you normally would for that framework.
 
 ## Before you begin
 
@@ -67,7 +67,7 @@ export const mastra = new Mastra({
 
 4. You can now call your Mastra endpoints over HTTP.
 
-   > **Warning:** Set up [authentication](https://mastra.ai/docs/server/auth) before exposing your endpoints publicly.
+   > **Warning:** Set up [authentication](https://mastra.ai/docs/auth/overview) before exposing your endpoints publicly.
 
 ## Studio
 

package/.docs/integrations/file-storage/amazon-s3.md

@@ -271,4 +271,4 @@ See [E2BSandbox reference](https://mastra.ai/integrations/sandboxes/e2b) for mor
 - [GCSFilesystem reference](https://mastra.ai/integrations/file-storage/google-cloud-storage)
 - [AzureBlobFilesystem reference](https://mastra.ai/integrations/file-storage/azure-blob)
 - [E2BSandbox reference](https://mastra.ai/integrations/sandboxes/e2b)
-- [Filesystem](https://mastra.ai/docs/workspace/filesystem)
+- [Filesystem](https://mastra.ai/docs/sandbox/filesystem)

package/.docs/integrations/file-storage/azure-blob.md

@@ -217,4 +217,4 @@ const config = filesystem.getMountConfig()
 - [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem)
 - [S3Filesystem reference](https://mastra.ai/integrations/file-storage/amazon-s3)
 - [GCSFilesystem reference](https://mastra.ai/integrations/file-storage/google-cloud-storage)
-- [Filesystem](https://mastra.ai/docs/workspace/filesystem)
+- [Filesystem](https://mastra.ai/docs/sandbox/filesystem)

package/.docs/integrations/file-storage/google-cloud-storage.md

@@ -194,4 +194,4 @@ See [E2BSandbox reference](https://mastra.ai/integrations/sandboxes/e2b) for mor
 - [S3Filesystem reference](https://mastra.ai/integrations/file-storage/amazon-s3)
 - [AzureBlobFilesystem reference](https://mastra.ai/integrations/file-storage/azure-blob)
 - [E2BSandbox reference](https://mastra.ai/integrations/sandboxes/e2b)
-- [Filesystem](https://mastra.ai/docs/workspace/filesystem)
+- [Filesystem](https://mastra.ai/docs/sandbox/filesystem)

package/.docs/integrations/file-storage/mesa.md

@@ -316,6 +316,6 @@ Read operations still work. Write operations throw `WorkspaceReadOnlyError`.
 ## Related
 
 - [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem)
-- [Filesystem docs](https://mastra.ai/docs/workspace/filesystem)
-- [Sandbox](https://mastra.ai/docs/workspace/sandbox)
+- [Filesystem docs](https://mastra.ai/docs/sandbox/filesystem)
+- [Sandbox](https://mastra.ai/docs/sandbox/overview)
 - [Mesa documentation](https://docs.mesa.dev/content/getting-started/introduction)

package/.docs/integrations/file-storage/vercel-files.md

@@ -184,5 +184,5 @@ const url = await filesystem.files.url('reports/q3.pdf')
 - [S3Filesystem reference](https://mastra.ai/integrations/file-storage/amazon-s3)
 - [GCSFilesystem reference](https://mastra.ai/integrations/file-storage/google-cloud-storage)
 - [AzureBlobFilesystem reference](https://mastra.ai/integrations/file-storage/azure-blob)
-- [Filesystem](https://mastra.ai/docs/workspace/filesystem)
+- [Filesystem](https://mastra.ai/docs/sandbox/filesystem)
 - [FilesSDK documentation](https://files-sdk.dev)

package/.docs/integrations/frameworks/astro.md

@@ -153,7 +153,7 @@ yarn add @mastra/ai-sdk@latest @ai-sdk/react ai
 bun add @mastra/ai-sdk@latest @ai-sdk/react ai
 ```
 
-Next, initialize AI Elements. When prompted, choose the default options:
+Next, initialize AI Elements. When prompted to select a component library, choose **Radix UI**, then accept the defaults for the remaining prompts:
 
 **npm**:
 
@@ -179,6 +179,10 @@ yarn dlx ai-elements@latest
 bun x ai-elements@latest
 ```
 
+> **Note:** The `ai-elements` command runs `shadcn add` against the AI Elements registry, which currently publishes Radix UI components only. Installing them into a Base UI project produces TypeScript errors, tracked in [vercel/ai-elements#383](https://github.com/vercel/ai-elements/issues/383).
+>
+> The component library prompt only appears when your project has no `components.json`. If you already have one, check that its `style` is a Radix option, such as `new-york` or a `radix-*` style, and not a `base-*` style, before running the command.
+
 This downloads the entire AI Elements UI component library into a `@/components/ai-elements` folder.
 
 ## Create a chat route
@@ -391,7 +395,7 @@ Congratulations on building your Mastra agent with Astro! 🎉
 From here, you can extend the project with your own tools and logic:
 
 - Learn more about [agents](https://mastra.ai/docs/agents/overview)
-- Give your agent its own [tools](https://mastra.ai/docs/agents/using-tools)
+- Give your agent its own [tools](https://mastra.ai/docs/agents/tools)
 - Add human-like [memory](https://mastra.ai/docs/memory/overview) to your agent
 
 When you're ready, read more about how Mastra integrates with AI SDK UI and how to deploy your agent anywhere:

package/.docs/integrations/frameworks/electron.md

@@ -497,7 +497,7 @@ Congratulations on building your Mastra agent with Electron! 🎉
 From here, you can extend the project with your own tools and logic:
 
 - Learn more about [agents](https://mastra.ai/docs/agents/overview)
-- Give your agent its own [tools](https://mastra.ai/docs/agents/using-tools)
+- Give your agent its own [tools](https://mastra.ai/docs/agents/tools)
 - Add human-like [memory](https://mastra.ai/docs/memory/overview) to your agent
 
 When you're ready, read more about how Mastra integrates with AI SDK UI and React, and how to deploy your agent anywhere:

package/.docs/integrations/frameworks/express.md

@@ -245,7 +245,7 @@ Congratulations on building your Mastra agent with Express! 🎉
 From here, you can extend the project with your own tools and logic:
 
 - Learn more about [agents](https://mastra.ai/docs/agents/overview)
-- Give your agent its own [tools](https://mastra.ai/docs/agents/using-tools)
+- Give your agent its own [tools](https://mastra.ai/docs/agents/tools)
 - Add human-like [memory](https://mastra.ai/docs/memory/overview) to your agent
 
 When you're ready, read more about how Mastra integrates with Express:

package/.docs/integrations/frameworks/hono.md

@@ -184,7 +184,7 @@ Congratulations on building your Mastra agent with Hono! 🎉
 From here, you can extend the project with your own tools and logic:
 
 - Learn more about [agents](https://mastra.ai/docs/agents/overview)
-- Give your agent its own [tools](https://mastra.ai/docs/agents/using-tools)
+- Give your agent its own [tools](https://mastra.ai/docs/agents/tools)
 - Add human-like [memory](https://mastra.ai/docs/memory/overview) to your agent
 
 When you're ready, read more about how Mastra integrates with Hono:

package/.docs/integrations/frameworks/nestjs.md

@@ -232,7 +232,7 @@ Both approaches use the same singleton `Mastra` instance registered by `MastraMo
 You now have a working Mastra agent running inside NestJS. To extend the project:
 
 - [Agents overview](https://mastra.ai/docs/agents/overview)
-- [Using tools](https://mastra.ai/docs/agents/using-tools)
+- [Using tools](https://mastra.ai/docs/agents/tools)
 - [Agent memory](https://mastra.ai/docs/memory/overview)
 
 For details on the NestJS integration:

package/.docs/integrations/frameworks/next-js.md

@@ -121,7 +121,7 @@ yarn add @mastra/ai-sdk@latest @ai-sdk/react ai
 bun add @mastra/ai-sdk@latest @ai-sdk/react ai
 ```
 
-Next, initialize AI Elements. When prompted, choose the default options:
+Next, initialize AI Elements. When prompted to select a component library, choose **Radix UI**, then accept the defaults for the remaining prompts:
 
 **npm**:
 
@@ -147,6 +147,10 @@ yarn dlx ai-elements@latest
 bun x ai-elements@latest
 ```
 
+> **Note:** The `ai-elements` command runs `shadcn add` against the AI Elements registry, which currently publishes Radix UI components only. Installing them into a Base UI project produces TypeScript errors, tracked in [vercel/ai-elements#383](https://github.com/vercel/ai-elements/issues/383).
+>
+> The component library prompt only appears when your project has no `components.json`. If you already have one, check that its `style` is a Radix option, such as `new-york` or a `radix-*` style, and not a `base-*` style, before running the command.
+
 This downloads the entire AI Elements UI component library into a `@/components/ai-elements` folder.
 
 ## Create a chat route
@@ -335,7 +339,7 @@ Congratulations on building your Mastra agent with Next.js! 🎉
 From here, you can extend the project with your own tools and logic:
 
 - Learn more about [agents](https://mastra.ai/docs/agents/overview)
-- Give your agent its own [tools](https://mastra.ai/docs/agents/using-tools)
+- Give your agent its own [tools](https://mastra.ai/docs/agents/tools)
 - Add human-like [memory](https://mastra.ai/docs/memory/overview) to your agent
 
 When you're ready, read more about how Mastra integrates with AI SDK UI and Next.js, and how to deploy your agent anywhere, including Vercel:

package/.docs/integrations/frameworks/nuxt.md

@@ -490,7 +490,7 @@ Congratulations on building your Mastra agent with Nuxt! 🎉
 From here, you can extend the project with your own tools and logic:
 
 - Learn more about [agents](https://mastra.ai/docs/agents/overview)
-- Give your agent its own [tools](https://mastra.ai/docs/agents/using-tools)
+- Give your agent its own [tools](https://mastra.ai/docs/agents/tools)
 - Add human-like [memory](https://mastra.ai/docs/memory/overview) to your agent
 
 When you're ready, read more about how Mastra integrates with AI SDK UI and Nuxt, and how to deploy your agent anywhere: