Docs development

info

Quick notes: Use the repository scripts in package.json for a single Docusaurus documentation workflow.

Preview locally

Start the docs preview server from the repository root:

npm run docs

Open http://localhost:3001 to view the site. The server hot-reloads when files under docusaurus-docs/docs/ are edited.

Recommended workflow

• Edit or add MDX files under docusaurus-docs/docs/
• Run npm run docs:docusaurus:build before pushing to catch broken links and route issues
• Create PRs that include docs changes and reference relevant issues

Docs structure

• docusaurus-docs/docs/index.mdx — homepage
• docusaurus-docs/docs/<section>/*.mdx — content pages
• docusaurus-docs/sidebars.js — navigation configuration

Components & conventions

• Use Card, Columns, CardGroup components for landing pages
• Keep paragraphs short and include examples where helpful
• Reuse schemas and code snippets from scripts/ and examples/ in the repo

Validation & formatting

• Link and route check: npm run docs:docusaurus:build
• Linting and formatting should follow the repository conventions (Prettier/ESLint when enabled in the editor)

Troubleshooting

• If the preview doesn't start, confirm npm install has completed and there are no local env issues
• For broken links, run npm run docs:docusaurus:build and fix or remove stale links

Contributing docs

When adding documentation pages, update docusaurus-docs/sidebars.js for any new top-level sections, and add tests or examples where useful.

Building new agents

All new agents should use the Unified Agent Platform for consistency and maintainability.

Quick start

1. Create agent descriptor in the owning package, for example packages/domain-<domain>/src/agents/<agent-name>.ts:

import { AgentDescriptor, getOrCreateFactory } from '../shared';
import { myTool } from '../../tools/my-tool';

export const MY_AGENT_DESCRIPTOR: AgentDescriptor = {
  profileId: 'my-agent',
  registryId: 'my-agent',
  defaultName: 'My Agent',
  defaultPrompt: 'You are an agent that...',
  scopePrefix: 'MY-FEATURE-',  // Optional namespace
  tools: [myTool],
  seedConfig: {
    alias: 'My Agent',
    shouldSeed: true,  // Auto-create default profile
  },
};

export async function getMyAgent(): Promise<Agent> {
  const factory = getOrCreateFactory(MY_AGENT_DESCRIPTOR);
  return factory.getAgent();
}

2. Export it from the domain loader/runtime so apps/runtime/src/mastra-runtime.ts can compose it:

import { getMyAgent } from './agents/my-agent';

export const mastra = new Mastra({
  agents: {
    myAgent: await getMyAgent(),
    // ... other agents
  },
});

3. Document your agent in docusaurus-docs/docs/<feature>/agents.mdx:

## My Agent

- **Registry ID:** `my-agent`
- **Profile ID:** `my-agent`
- **Purpose:** Brief description
- **Code:** packages/domain-my-feature/src/agents/my-agent.ts

### Usage

\`\`\`ts
import { getMyAgent } from '@maf/domain-my-feature/agents/my-agent';

const agent = await getMyAgent();
const result = await agent.generate([
  { role: 'user', content: 'Your prompt here' }
]);
\`\`\`

Best practices

• ✅ Use getOrCreateFactory() for lazy agent loading
• ✅ Provide descriptive profileId matching database records
• ✅ Use scopePrefix for multi-tenant scenarios (e.g., K12-, TAP-)
• ✅ Enable debug logging during dev: MASTRA_DEBUG_AGENT_FACTORY=true
• ❌ Don't create agents before configureGlobalAgentDeps() is called
• ❌ Don't use top-level await for agent creation
• ❌ Don't implement custom caching logic (factory handles it)

See Unified Agent Platform for complete documentation.