@mastra/mcp-docs-server 1.2.13-alpha.1 → 1.2.13-alpha.11

package/.docs/docs/server/mastra-client.md

@@ -69,6 +69,66 @@ The Mastra Client SDK exposes all resources served by the Mastra Server.
 - **[Logs](https://mastra.ai/reference/client-js/logs)**: View logs and debug system behavior.
 - **[Telemetry](https://mastra.ai/reference/client-js/telemetry)**: View app performance and trace activity.
 
+## Create and run stored workflows
+
+Use `upsertStoredWorkflow()` to create or replace a persisted workflow definition. A successful upsert validates the complete definition, registers it with the running Mastra instance, and makes it available through the standard workflow execution API.
+
+The following example creates a mapping workflow, reads the stored definition, runs it, and then deletes it:
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+import type { UpsertStoredWorkflowParams } from '@mastra/client-js'
+
+const client = new MastraClient({
+  baseUrl: process.env.MASTRA_API_URL || 'http://localhost:4111',
+})
+
+const definition = {
+  id: 'greeting-workflow',
+  description: 'Returns a greeting for the supplied name',
+  inputSchema: {
+    type: 'object',
+    properties: { name: { type: 'string' } },
+    required: ['name'],
+  },
+  outputSchema: {
+    type: 'object',
+    properties: { message: { type: 'string' } },
+    required: ['message'],
+  },
+  graph: [
+    {
+      type: 'mapping',
+      id: 'create-greeting',
+      mapConfig: JSON.stringify({
+        message: { template: 'Hello, ${initData.name}!' },
+      }),
+    },
+  ],
+} satisfies UpsertStoredWorkflowParams
+
+await client.upsertStoredWorkflow(definition)
+
+const storedWorkflow = client.getStoredWorkflow(definition.id)
+const storedDefinition = await storedWorkflow.details()
+
+const workflow = client.getWorkflow(storedDefinition.id)
+const run = await workflow.createRun()
+const result = await run.startAsync({ inputData: { name: 'Ada' } })
+
+console.log(result)
+
+await storedWorkflow.delete()
+```
+
+Use `listStoredWorkflows()` to list persisted definitions. Calling `upsertStoredWorkflow()` again with the same `id` replaces the stored definition and live workflow registration.
+
+> **Warning:** Durable storage requires a configured storage adapter that supports the `workflowDefinitions` domain. Without that domain, Core can register a workflow in memory, but the server's stored-workflow API can't preserve it across restarts.
+>
+> Stored definitions support declarative agent, tool, mapping, nested workflow, parallel, foreach, sleep, sleep-until, conditional, and loop entries. They can't contain JavaScript closures. Conditional and loop logic must use the declarative predicate format, and referenced agents, tools, and nested workflows must already be registered.
+>
+> Authenticated servers require `stored-workflows:read` or `stored-workflows:write` for definition operations and `workflows:execute` to run the workflow.
+
 ## Generating responses
 
 Call `.generate()` with a string prompt:

package/.docs/docs/server/pubsub.md

@@ -124,6 +124,6 @@ Visit the [PubSub reference](https://mastra.ai/reference/pubsub/base) for the fu
 
 - [PubSub reference](https://mastra.ai/reference/pubsub/base)
 - [Mastra class](https://mastra.ai/reference/core/mastra-class)
+- [Workers](https://mastra.ai/docs/deployment/workers): Run workflow orchestration and background tasks in dedicated processes using PubSub
 - [Background task streaming](https://mastra.ai/docs/long-running-agents/background-tasks)
-- [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows)
-- [Workers](https://mastra.ai/docs/deployment/workers): Run workflow orchestration and background tasks in dedicated processes using PubSub
+- [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows)

package/.docs/docs/studio/observability.md

@@ -96,6 +96,10 @@ Visit the [metrics overview](https://mastra.ai/docs/observability/metrics/overvi
 
 When you run an agent or workflow, the Observability tab displays traces that highlight the key AI operations such as model calls, tool executions, and workflow steps. Follow these traces to see how data moves, where time is spent, and what's happening under the hood.
 
+Above the trace list, open **Columns** to show or hide input, entity, duration, input token, output token, estimated cost, and custom metadata columns. To display custom metadata, add the top-level key used in `tracingOptions.metadata`. Studio saves the selection in browser storage for the current Mastra server and API prefix.
+
+Token and estimated cost columns require an observability store that supports metrics. These columns stay hidden in the **Branches** view because several branch rows can belong to the same trace.
+
 Tracing filters out low-level framework details so your traces stay focused and readable. Visit the [tracing overview](https://mastra.ai/docs/observability/tracing/overview) for more details.
 
 To export a trace, select **Download trace JSON** in the trace panel header. This saves the entire trace as a `trace-<id>.json` file, with every span and its full input, output, metadata, and attributes. Use it to share a trace or attach it to a bug report, or alternatively build an evaluation dataset offline.

package/.docs/docs/studio/overview.md

@@ -103,13 +103,13 @@ The Scorers tab displays the results of your agent's scorers as they run. When m
 
 Create and manage collections of test cases to evaluate your agents and workflows. Import items from CSV or JSON and define input and ground-truth schemas, plus pin to specific versions so you can reproduce experiments exactly. Run experiments with [scorers](https://mastra.ai/docs/evals/overview) to compare quality across prompts, models, or code changes.
 
-See [datasets overview](https://mastra.ai/docs/evals/datasets/overview) for the full API and versioning details.
+See [datasets overview](https://mastra.ai/docs/datasets/overview) for the full API and versioning details.
 
 ### Experiments
 
 Run all items in a dataset against an agent, workflow, or scorer and collect the results in one place. Select a target, optionally attach scorers, and trigger the experiment. The results view shows each item's input, output, status, and individual score breakdowns. Compare two experiments side by side to measure the impact of prompt, model, or code changes.
 
-See [datasets overview](https://mastra.ai/docs/evals/datasets/overview) for setup details.
+See [datasets overview](https://mastra.ai/docs/datasets/overview) for setup details.
 
 ## Observability
 

package/.docs/docs/workflows/overview.md

@@ -545,5 +545,5 @@ For a closer look at workflows, see our [Workflow Guide](https://mastra.ai/guide
 - [Control Flow](https://mastra.ai/docs/workflows/control-flow)
 - [Suspend and Resume](https://mastra.ai/docs/workflows/suspend-and-resume)
 - [Error Handling](https://mastra.ai/docs/workflows/error-handling)
-- [Workers](https://mastra.ai/docs/deployment/workers): Offload workflow orchestration to dedicated processes in production
+- [Workers](https://mastra.ai/docs/deployment/workers): Run workflow execution in dedicated background processes
 - 📹 [Agentic workflows with Mastra workshop](https://www.youtube.com/watch?v=HGt8pVPpX9g)

package/.docs/docs/workflows/scheduled-workflows.md

@@ -181,4 +181,5 @@ Manage Inngest schedules from the [Inngest dashboard](https://www.inngest.com/do
 
 - [Workflow overview](https://mastra.ai/docs/workflows/overview)
 - [Suspend and resume](https://mastra.ai/docs/workflows/suspend-and-resume)
+- [Workers](https://mastra.ai/docs/deployment/workers): The [scheduler worker](https://mastra.ai/docs/deployment/workers) runs cron schedules in a dedicated process
 - [Agent schedules](https://mastra.ai/docs/long-running-agents/schedules): Run an agent rather than a workflow on a cron schedule, and manage both schedule types at runtime through `mastra.schedules`.

package/.docs/docs/workspace/search.md

@@ -280,5 +280,5 @@ When you configure search on a workspace, agents receive tools for searching and
 ## Related
 
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)
-- [RAG overview](https://mastra.ai/docs/rag/overview)
+- [RAG overview](https://mastra.ai/guides/rag/overview)
 - [Workspace class reference](https://mastra.ai/reference/workspace/workspace-class)

package/.docs/guides/deployment/kubernetes.md

@@ -294,5 +294,7 @@ The pod that handles the approval loads the suspended run from Postgres. It then
 
 - [PubSub](https://mastra.ai/docs/server/pubsub)
 - [Durable agents](https://mastra.ai/docs/long-running-agents/durable-agents)
+- [Workers](https://mastra.ai/docs/deployment/workers): Split background processing into separate containers on Kubernetes
+- [Worker deployment guide](https://mastra.ai/guides/deployment/mastra-workers): Full Kubernetes manifests for orchestration, scheduler, and background task workers
 - [Mastra server](https://mastra.ai/docs/server/mastra-server)
 - [Deployment overview](https://mastra.ai/docs/deployment/overview)

package/.docs/guides/deployment/mastra-workers.md

@@ -2,7 +2,7 @@
 
 # Deploy Mastra workers
 
-Run [Mastra workers](https://mastra.ai/docs/deployment/workers) as separate processes so you can scale orchestration, scheduling, and background tasks independently from the API. This guide walks through a fully split deployment using Docker Compose.
+Run [Mastra workers](https://mastra.ai/docs/deployment/workers) as separate processes so you can scale orchestration, scheduling, and background tasks independently from the API. This guide walks through a fully split deployment using Docker Compose or Kubernetes.
 
 > **Info:** This guide covers splitting workers into their own containers. If you only need workers to run in-process alongside the API, see [Workers](https://mastra.ai/docs/deployment/workers). No extra setup is required.
 
@@ -11,7 +11,7 @@ Run [Mastra workers](https://mastra.ai/docs/deployment/workers) as separate proc
 You'll need:
 
 - A [Mastra application](https://mastra.ai/guides/getting-started/quickstart)
-- [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/)
+- [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/), or a [Kubernetes](https://kubernetes.io/docs/setup/) cluster with [`kubectl`](https://kubernetes.io/docs/tasks/tools/)
 - A distributed PubSub backend: [Redis](https://redis.io/) for [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams), or a [Google Cloud](https://cloud.google.com/) project for [`GoogleCloudPubSub`](https://mastra.ai/reference/pubsub/google-cloud-pubsub)
 - A shared database reachable from every container. See [supported storage backends](https://mastra.ai/reference/workers/overview) for the full list.
 
@@ -83,9 +83,13 @@ Any [supported storage backend](https://mastra.ai/reference/workers/overview) wo
    CMD ["node", "index.mjs"]
    ```
 
-3. Create a `docker-compose.yml` that runs the fully split topology. The file defines six services: a database, a PubSub backend, the API server, and three workers. Each worker container runs the same image with a different `MASTRA_WORKERS` value to control which worker starts.
+3. Define the fully split topology. The setup runs six services: a database, a PubSub backend, the API server, and three workers. Each worker runs the same image with a different `MASTRA_WORKERS` value to control which worker starts.
 
-   The API container sets `MASTRA_WORKERS: "false"` to disable all event processing. The orchestration worker sets `MASTRA_STEP_EXECUTION_URL` to point step execution requests at the API's internal URL. See [step execution URL](#step-execution-url) for details.
+   The API sets `MASTRA_WORKERS: "false"` to disable all event processing. The orchestration worker sets `MASTRA_STEP_EXECUTION_URL` to point step execution requests at the API's internal URL. See [step execution URL](#step-execution-url) for details.
+
+   All services share a `MASTRA_WORKER_AUTH_TOKEN`. Workers include this token in requests to the API so the API can verify the caller is a trusted internal service. See [worker authentication](https://mastra.ai/docs/server/auth/workers) for details.
+
+   **Docker Compose**:
 
    ```yaml
    services:
@@ -123,6 +127,7 @@ Any [supported storage backend](https://mastra.ai/reference/workers/overview) wo
          DATABASE_URL: postgres://mastra:${POSTGRES_PASSWORD}@postgres:5432/mastra
          REDIS_URL: redis://redis:6379
          MASTRA_WORKERS: 'false'
+         MASTRA_WORKER_AUTH_TOKEN: ${MASTRA_WORKER_AUTH_TOKEN}
        depends_on:
          postgres:
            condition: service_healthy
@@ -141,6 +146,7 @@ Any [supported storage backend](https://mastra.ai/reference/workers/overview) wo
          REDIS_URL: redis://redis:6379
          MASTRA_WORKERS: orchestration
          MASTRA_STEP_EXECUTION_URL: http://api:4111/api
+         MASTRA_WORKER_AUTH_TOKEN: ${MASTRA_WORKER_AUTH_TOKEN}
        depends_on:
          api:
            condition: service_healthy
@@ -151,6 +157,7 @@ Any [supported storage backend](https://mastra.ai/reference/workers/overview) wo
          DATABASE_URL: postgres://mastra:${POSTGRES_PASSWORD}@postgres:5432/mastra
          REDIS_URL: redis://redis:6379
          MASTRA_WORKERS: scheduler
+         MASTRA_WORKER_AUTH_TOKEN: ${MASTRA_WORKER_AUTH_TOKEN}
        depends_on:
          api:
            condition: service_healthy
@@ -161,6 +168,7 @@ Any [supported storage backend](https://mastra.ai/reference/workers/overview) wo
          DATABASE_URL: postgres://mastra:${POSTGRES_PASSWORD}@postgres:5432/mastra
          REDIS_URL: redis://redis:6379
          MASTRA_WORKERS: backgroundTasks
+         MASTRA_WORKER_AUTH_TOKEN: ${MASTRA_WORKER_AUTH_TOKEN}
        depends_on:
          api:
            condition: service_healthy
@@ -173,11 +181,296 @@ Any [supported storage backend](https://mastra.ai/reference/workers/overview) wo
 
    ```bash
    POSTGRES_PASSWORD=your-secure-password
+   MASTRA_WORKER_AUTH_TOKEN=your-shared-secret-token
    ```
 
    > **Note:** Remember to set any other environment variables your application needs (e.g., your [model provider](https://mastra.ai/models/providers) API key).
 
-4. Start the stack and verify the API responds:
+   **Kubernetes**:
+
+   Create a namespace and a Secret with your connection strings:
+
+   ```yaml
+   apiVersion: v1
+   kind: Namespace
+   metadata:
+     name: mastra-workers
+   ```
+
+   ```bash
+   kubectl apply -f k8s/namespace.yaml
+   kubectl create secret generic mastra-secrets -n mastra-workers \
+     --from-literal=POSTGRES_PASSWORD='your-password' \
+     --from-literal=DATABASE_URL='postgresql://mastra:your-password@postgres:5432/mastra' \
+     --from-literal=REDIS_URL='redis://redis:6379' \
+     --from-literal=MASTRA_WORKER_AUTH_TOKEN='your-shared-token'
+   ```
+
+   > **Note:** Add any other environment variables your application needs (e.g., your [model provider](https://mastra.ai/models/providers) API key) to the Secret or as additional `--from-literal` entries.
+
+   Build and push the Docker image to a registry your cluster can pull from:
+
+   ```bash
+   docker build -t your-registry/mastra-workers:latest ./app
+   docker push your-registry/mastra-workers:latest
+   ```
+
+   Apply Deployments and Services for the database, PubSub backend, API, and three workers. The example below uses in-cluster Postgres and Redis. In production, use managed services (e.g., Amazon RDS, Cloud SQL, ElastiCache, Memorystore).
+
+   ```yaml
+   apiVersion: apps/v1
+   kind: Deployment
+   metadata:
+     name: postgres
+     namespace: mastra-workers
+   spec:
+     replicas: 1
+     selector:
+       matchLabels:
+         app: postgres
+     template:
+       metadata:
+         labels:
+           app: postgres
+       spec:
+         containers:
+           - name: postgres
+             image: postgres:16-alpine
+             ports:
+               - containerPort: 5432
+             env:
+               - name: POSTGRES_USER
+                 value: mastra
+               - name: POSTGRES_PASSWORD
+                 valueFrom:
+                   secretKeyRef:
+                     name: mastra-secrets
+                     key: POSTGRES_PASSWORD
+               - name: POSTGRES_DB
+                 value: mastra
+             volumeMounts:
+               - name: pgdata
+                 mountPath: /var/lib/postgresql/data
+         volumes:
+           - name: pgdata
+             emptyDir: {}
+   ---
+   apiVersion: v1
+   kind: Service
+   metadata:
+     name: postgres
+     namespace: mastra-workers
+   spec:
+     selector:
+       app: postgres
+     ports:
+       - port: 5432
+         targetPort: 5432
+   ```
+
+   > **Caution:** The Postgres example above uses `emptyDir` for storage, which means data is lost when the pod restarts. In production, replace it with a `PersistentVolumeClaim` or use a managed database service.
+
+   ```yaml
+   apiVersion: apps/v1
+   kind: Deployment
+   metadata:
+     name: redis
+     namespace: mastra-workers
+   spec:
+     replicas: 1
+     selector:
+       matchLabels:
+         app: redis
+     template:
+       metadata:
+         labels:
+           app: redis
+       spec:
+         containers:
+           - name: redis
+             image: redis:7-alpine
+             args: ['--appendonly', 'yes']
+             ports:
+               - containerPort: 6379
+   ---
+   apiVersion: v1
+   kind: Service
+   metadata:
+     name: redis
+     namespace: mastra-workers
+   spec:
+     selector:
+       app: redis
+     ports:
+       - port: 6379
+         targetPort: 6379
+   ```
+
+   ```yaml
+   apiVersion: apps/v1
+   kind: Deployment
+   metadata:
+     name: api
+     namespace: mastra-workers
+   spec:
+     replicas: 1
+     selector:
+       matchLabels:
+         app: api
+     template:
+       metadata:
+         labels:
+           app: api
+       spec:
+         containers:
+           - name: api
+             image: your-registry/mastra-workers:latest
+             ports:
+               - containerPort: 4111
+             env:
+               - name: MASTRA_WORKERS
+                 value: 'false'
+             envFrom:
+               - secretRef:
+                   name: mastra-secrets
+             readinessProbe:
+               httpGet:
+                 path: /api/agents
+                 port: 4111
+               initialDelaySeconds: 10
+               periodSeconds: 5
+             livenessProbe:
+               httpGet:
+                 path: /api/agents
+                 port: 4111
+               initialDelaySeconds: 15
+               periodSeconds: 10
+             resources:
+               requests:
+                 cpu: 500m
+                 memory: 512Mi
+   ---
+   apiVersion: v1
+   kind: Service
+   metadata:
+     name: api
+     namespace: mastra-workers
+   spec:
+     selector:
+       app: api
+     ports:
+       - port: 4111
+         targetPort: 4111
+   ```
+
+   ```yaml
+   apiVersion: apps/v1
+   kind: Deployment
+   metadata:
+     name: orchestration-worker
+     namespace: mastra-workers
+   spec:
+     replicas: 1
+     selector:
+       matchLabels:
+         app: orchestration-worker
+     template:
+       metadata:
+         labels:
+           app: orchestration-worker
+       spec:
+         containers:
+           - name: worker
+             image: your-registry/mastra-workers:latest
+             env:
+               - name: MASTRA_WORKERS
+                 value: orchestration
+               - name: MASTRA_STEP_EXECUTION_URL
+                 value: http://api:4111/api
+             envFrom:
+               - secretRef:
+                   name: mastra-secrets
+             resources:
+               requests:
+                 cpu: 250m
+                 memory: 256Mi
+   ```
+
+   ```yaml
+   apiVersion: apps/v1
+   kind: Deployment
+   metadata:
+     name: scheduler-worker
+     namespace: mastra-workers
+   spec:
+     replicas: 1
+     selector:
+       matchLabels:
+         app: scheduler-worker
+     template:
+       metadata:
+         labels:
+           app: scheduler-worker
+       spec:
+         containers:
+           - name: worker
+             image: your-registry/mastra-workers:latest
+             env:
+               - name: MASTRA_WORKERS
+                 value: scheduler
+             envFrom:
+               - secretRef:
+                   name: mastra-secrets
+             resources:
+               requests:
+                 cpu: 250m
+                 memory: 256Mi
+   ```
+
+   ```yaml
+   apiVersion: apps/v1
+   kind: Deployment
+   metadata:
+     name: background-task-worker
+     namespace: mastra-workers
+   spec:
+     replicas: 1
+     selector:
+       matchLabels:
+         app: background-task-worker
+     template:
+       metadata:
+         labels:
+           app: background-task-worker
+       spec:
+         containers:
+           - name: worker
+             image: your-registry/mastra-workers:latest
+             env:
+               - name: MASTRA_WORKERS
+                 value: backgroundTasks
+             envFrom:
+               - secretRef:
+                   name: mastra-secrets
+             resources:
+               requests:
+                 cpu: 250m
+                 memory: 256Mi
+   ```
+
+   Apply all manifests and wait for the API to become ready:
+
+   ```bash
+   kubectl apply -f k8s/
+   kubectl wait -n mastra-workers --for=condition=ready pod -l app=api --timeout=90s
+   kubectl wait -n mastra-workers --for=condition=ready pod -l app=orchestration-worker --timeout=60s
+   kubectl wait -n mastra-workers --for=condition=ready pod -l app=scheduler-worker --timeout=60s
+   kubectl wait -n mastra-workers --for=condition=ready pod -l app=background-task-worker --timeout=60s
+   ```
+
+4. Verify the stack is running and the API responds:
+
+   **Docker Compose**:
 
    ```bash
    docker compose up -d
@@ -185,6 +478,21 @@ Any [supported storage backend](https://mastra.ai/reference/workers/overview) wo
    curl http://localhost:4111/api/agents
    ```
 
+   **Kubernetes**:
+
+   ```bash
+   kubectl get pods -n mastra-workers
+   kubectl port-forward -n mastra-workers svc/api 4111:4111
+   ```
+
+   In a separate terminal:
+
+   ```bash
+   curl http://localhost:4111/api/agents
+   ```
+
+   A JSON list of your agents confirms the API and workers are running.
+
 ## Step execution URL
 
 In a fully split deployment, the orchestration worker runs in a separate container from the API. When it processes a workflow event, it delegates step execution to the API over HTTP.
@@ -203,11 +511,46 @@ Without this variable, the orchestration worker attempts to execute steps in-pro
 
 The orchestration and background task workers are safe to scale horizontally. PubSub consumer groups distribute events across instances, so each event is processed once:
 
+**Docker Compose**:
+
 ```bash
 docker compose up -d --scale orchestration-worker=3
 docker compose up -d --scale background-task-worker=2
 ```
 
+**Kubernetes**:
+
+```bash
+kubectl scale deployment/orchestration-worker -n mastra-workers --replicas=3
+kubectl scale deployment/background-task-worker -n mastra-workers --replicas=2
+```
+
+For automatic scaling, add a HorizontalPodAutoscaler:
+
+```yaml
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: orchestration-worker
+  namespace: mastra-workers
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: orchestration-worker
+  minReplicas: 1
+  maxReplicas: 10
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: 70
+```
+
+> **Note:** CPU-based autoscaling needs the [metrics-server](https://github.com/kubernetes-sigs/metrics-server) running in the cluster. Managed clusters like GKE, EKS, and AKS include it by default.
+
 The API can also scale horizontally behind a load balancer.
 
 **Don't scale the scheduler worker.** Run exactly one instance. Multiple schedulers polling the same storage fire duplicate events for the same schedule.
@@ -229,4 +572,5 @@ Workers recover from crashes because the distributed PubSub backend persists una
 - [Workers reference](https://mastra.ai/reference/workers/overview): Configuration details for all worker types
 - [CLI reference](https://mastra.ai/reference/cli/mastra): `mastra worker build` and `mastra worker start`
 - [PubSub](https://mastra.ai/docs/server/pubsub): Event delivery backends
-- [Deploy a Mastra server](https://mastra.ai/docs/deployment/mastra-server): Build output and server configuration
+- [Deploy a Mastra server](https://mastra.ai/docs/deployment/mastra-server): Build output and server configuration
+- [Deploy Mastra to Kubernetes](https://mastra.ai/guides/deployment/kubernetes): Multi-pod deployment with durable agents

package/.docs/guides/deployment/vercel.md

@@ -86,6 +86,8 @@ export const mastra = new Mastra({
 
 After deploying, Studio is available at the root URL (`https://<your-project>.vercel.app/`) and the API remains at `/api/*`. Studio automatically connects to the API on the same origin, so you don't need additional environment variables.
 
+Studio serves its own pages from the CDN, and every other path goes to your server, so routes you add with [`registerApiRoute()`](https://mastra.ai/docs/server/custom-api-routes) stay reachable at their own paths. Avoid giving a custom route a path that Studio already uses (for example `/agents` or `/workflows`), since Studio claims those first.
+
 > **Warning:** Once Studio is connected to your Mastra server, it has full access to your agents, workflows, and tools. Be sure to secure it properly in production (e.g. behind authentication, VPN, etc.) to prevent unauthorized access.
 
 ## Optional overrides

package/.docs/guides/getting-started/quickstart.md

@@ -2,11 +2,11 @@
 
 # Mastra Quickstart
 
-**For AI agents:** Create a new Mastra project non-interactively with `npm create mastra@latest <project-name> -- --llm <provider>`, replacing `<provider>` with `openai`, `anthropic`, `google`, or `xai`. For a minimal project without an agent or model provider, use `npm create mastra@latest <project-name> -- --empty`. To build a Mastra project from scratch, see the [manual installation guide](https://mastra.ai/docs/getting-started/manual-install).
+**For AI agents:** Create a new Mastra project non-interactively with `npm create mastra@latest <project-name> -- --llm <provider>`, replacing `<provider>` with `openai`, `anthropic`, `google`, or `xai`. For a minimal project without an agent or model provider, use `npm create mastra@latest <project-name> -- --empty`. To build a Mastra project from scratch, see the [manual installation guide](https://mastra.ai/guides/getting-started/manual-install).
 
 The `create-mastra` CLI is the quickest way to start a Mastra project. It creates an agent harness with workspace tools, memory, task tracking, web access, schedules, storage, and observability.
 
-For more control, see the [manual installation guide](https://mastra.ai/docs/getting-started/manual-install). To add Mastra to an existing project, use [`mastra init`](https://mastra.ai/reference/cli/mastra).
+For more control, see the [manual installation guide](https://mastra.ai/guides/getting-started/manual-install). To add Mastra to an existing project, use [`mastra init`](https://mastra.ai/reference/cli/mastra).
 
 > **📹 Watch:** Watch the [Mastra AI agent course](https://www.youtube.com/watch?v=lCmf_qrGfGA) for a guided introduction to building agents with Mastra.
 
@@ -83,6 +83,6 @@ Open [Studio at localhost:4111](http://localhost:4111), select the agent, and se
 ## Next steps
 
 - Integrate Mastra with [Next.js](https://mastra.ai/guides/getting-started/next-js), [React](https://mastra.ai/guides/getting-started/vite-react), or [Astro](https://mastra.ai/guides/getting-started/astro)
-- Learn how to [build Mastra with AI](https://mastra.ai/docs/getting-started/build-with-ai)
+- Learn how to [build Mastra with AI](https://mastra.ai/reference/build-with-ai)
 - Build an agent from scratch with a [guide](https://mastra.ai/guides)
 - Watch the [Mastra YouTube channel](https://www.youtube.com/@mastra-ai)

package/.docs/{docs → guides}/rag/chunking-and-embedding.md

@@ -181,5 +181,5 @@ For more examples of different chunking strategies and embedding configurations,
 
 For more details on vector databases and embeddings, see:
 
-- [Vector Databases](https://mastra.ai/docs/rag/vector-databases)
+- [Vector Databases](https://mastra.ai/guides/rag/vector-databases)
 - [Embedding API Reference](https://mastra.ai/reference/rag/embeddings)

package/.docs/{docs → guides}/rag/graph-rag.md

@@ -14,7 +14,7 @@ GraphRAG is particularly effective when:
 - Understanding connections between concepts is important
 - Simple vector similarity misses important contextual relationships
 
-For straightforward semantic search without relationship traversal, use [standard retrieval methods](https://mastra.ai/docs/rag/retrieval).
+For straightforward semantic search without relationship traversal, use [standard retrieval methods](https://mastra.ai/guides/rag/retrieval).
 
 ## How GraphRAG works
 

package/.docs/{docs → guides}/rag/overview.md

@@ -63,11 +63,11 @@ This example shows the essentials. Initialize a document and create chunks, then
 
 ## Document processing
 
-The basic building block of RAG is document processing. Documents can be chunked using strategies (recursive, sliding window, etc.) and enriched with metadata. See the [chunking and embedding doc](https://mastra.ai/docs/rag/chunking-and-embedding).
+The basic building block of RAG is document processing. Documents can be chunked using strategies (recursive, sliding window, etc.) and enriched with metadata. See the [chunking and embedding doc](https://mastra.ai/guides/rag/chunking-and-embedding).
 
 ## Vector storage
 
-Mastra supports multiple vector stores for embedding persistence and similarity search, including pgvector, Pinecone, Qdrant, and MongoDB. See the [vector database doc](https://mastra.ai/docs/rag/vector-databases).
+Mastra supports multiple vector stores for embedding persistence and similarity search, including pgvector, Pinecone, Qdrant, and MongoDB. See the [vector database doc](https://mastra.ai/guides/rag/vector-databases).
 
 ## More resources
 

package/.docs/{docs → guides}/rag/retrieval.md

@@ -517,4 +517,4 @@ The re-ranked results combine vector similarity with semantic understanding to i
 
 For more details about re-ranking, see the [rerank()](https://mastra.ai/reference/rag/rerankWithScorer) method.
 
-For graph-based retrieval that follows connections between chunks, see the [GraphRAG](https://mastra.ai/docs/rag/graph-rag) documentation.
+For graph-based retrieval that follows connections between chunks, see the [GraphRAG](https://mastra.ai/guides/rag/graph-rag) documentation.