Documentation Operations

Overview

This runbook covers operational procedures for managing SO1 documentation agents, including Mintlify site authoring, OpenAPI specification generation, and operational runbook creation. These procedures ensure comprehensive, accurate, and maintainable documentation across the platform. Purpose: Provide step-by-step instructions for creating and maintaining platform documentation Scope: Mintlify documentation sites, API reference generation, runbook authoring, content management Target Audience: Technical writers, documentation engineers, platform operators

Prerequisites

Required Access

GitHub repository access (so1-io/so1-content)
Mintlify dashboard access (team: so1-io)
Control Plane API access (CONTROL_PLANE_API_KEY)
Veritas prompt library access

Required Tools

Mintlify CLI (npx mintlify dev)
OpenCode with documentation agents installed
Git CLI
Markdown editor (VS Code recommended)
curl for API testing

Required Knowledge

Markdown syntax and MDX extensions
Understanding of Mintlify component library
Familiarity with OpenAPI/Swagger specifications
Basic knowledge of API documentation standards

Procedure 1: Author Mintlify Documentation

Step 1: Plan Documentation Structure

Define the documentation scope:

interface DocStructure {
  section: 'agents' | 'architecture' | 'runbooks' | 'api-reference';
  pages: {
    title: string;
    path: string;
    description: string;
    priority: 'high' | 'medium' | 'low';
  }[];
}

Step 2: Invoke Mintlify Author Agent

curl -X POST https://control-plane.so1.io/api/v1/agents/mintlify-author/generate \
  -H "Authorization: Bearer ${CONTROL_PLANE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "page_type": "agent_reference",
    "agent_name": "workflow-architect",
    "agent_metadata": {
      "domain": "automation",
      "stage": "design",
      "version": "1.2.0",
      "description": "Designs and optimizes n8n workflow architectures for complex automation pipelines",
      "outputs": [
        "n8n workflow JSON definitions",
        "Performance optimization recommendations",
        "Integration specifications"
      ]
    },
    "include_sections": [
      "overview",
      "capabilities",
      "usage_examples",
      "outputs",
      "forge_compliance",
      "integration_points",
      "related_agents"
    ],
    "style": "technical",
    "target_audience": "automation_engineers"
  }' | jq '.'

Expected Response:

{
  "generation_id": "gen_5Xy9mPqRs",
  "file_path": "agents/automation/workflow-architect.mdx",
  "content": "---\ntitle: 'Workflow Architect'\ndescription: 'Designs and optimizes n8n workflow architectures'\nicon: 'diagram-project'\n---\n\n## Overview\n\n<Info>\n  **Use this agent when** you need to design complex n8n workflows...\n</Info>\n\n...",
  "word_count": 1847,
  "components_used": [
    "Info",
    "CardGroup",
    "Card",
    "Tabs",
    "Tab",
    "CodeGroup",
    "AccordionGroup",
    "Accordion"
  ]
}

Step 3: Review and Customize Generated Content

# Save generated content
curl -s https://control-plane.so1.io/api/v1/agents/mintlify-author/generations/gen_5Xy9mPqRs \
  -H "Authorization: Bearer ${CONTROL_PLANE_API_KEY}" \
  | jq -r '.content' > agents/automation/workflow-architect.mdx

# Preview locally
npx mintlify dev

# Open: http://localhost:3000/agents/automation/workflow-architect

Step 4: Validate Documentation Quality

Quality Checklist:

Step 5: Deploy Documentation

# Add to git
git add agents/automation/workflow-architect.mdx

# Update mint.json navigation if needed
# (mintlify-author agent typically generates navigation updates)

# Commit and push
git commit -m "Add workflow-architect agent documentation"
git push origin main

# Mintlify auto-deploys from main branch
# Verify deployment at https://docs.so1.io

Procedure 2: Generate API Documentation

Step 1: Extract API Endpoints from Codebase

# For Hono-based APIs, scan route definitions
curl -X POST https://control-plane.so1.io/api/v1/agents/api-documenter/analyze \
  -H "Authorization: Bearer ${CONTROL_PLANE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "github",
      "repo": "so1-io/control-plane",
      "paths": ["src/routes/**/*.ts"]
    },
    "framework": "hono",
    "output_format": "openapi_3.1"
  }' | jq '.'

Expected Response:

{
  "analysis_id": "ana_7TnVw9Kj2m",
  "endpoints_found": 42,
  "specification": {
    "openapi": "3.1.0",
    "info": {
      "title": "SO1 Control Plane API",
      "version": "1.2.3",
      "description": "Core orchestration and automation API"
    },
    "servers": [
      {"url": "https://control-plane.so1.io", "description": "Production"},
      {"url": "https://staging.control-plane.so1.io", "description": "Staging"}
    ],
    "paths": {
      "/api/v1/workflows": {
        "get": {
          "summary": "List workflows",
          "parameters": [
            {"name": "status", "in": "query", "schema": {"type": "string", "enum": ["active", "inactive"]}}
          ],
          "responses": {
            "200": {
              "description": "List of workflows",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "array",
                    "items": {"$ref": "#/components/schemas/Workflow"}
                  }
                }
              }
            }
          }
        }
      }
    },
    "components": {
      "schemas": {
        "Workflow": {
          "type": "object",
          "properties": {
            "id": {"type": "string", "format": "uuid"},
            "name": {"type": "string"},
            "status": {"type": "string", "enum": ["active", "inactive", "failed"]}
          }
        }
      }
    }
  }
}

Step 2: Enhance API Specification

# Add descriptions, examples, and authentication details
curl -X POST https://control-plane.so1.io/api/v1/agents/api-documenter/enhance \
  -H "Authorization: Bearer ${CONTROL_PLANE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "analysis_id": "ana_7TnVw9Kj2m",
    "enhancements": {
      "add_examples": true,
      "add_error_responses": true,
      "add_authentication": {
        "type": "bearer",
        "description": "Use Control Plane API key"
      },
      "add_rate_limits": {
        "default": "100/minute",
        "authenticated": "1000/minute"
      }
    }
  }' | jq '.'

Step 3: Generate Mintlify API Reference Pages

# Convert OpenAPI spec to Mintlify MDX pages
curl -X POST https://control-plane.so1.io/api/v1/agents/api-documenter/convert \
  -H "Authorization: Bearer ${CONTROL_PLANE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "specification_id": "ana_7TnVw9Kj2m",
    "output_format": "mintlify",
    "organize_by": "resource",
    "include_code_examples": true,
    "languages": ["curl", "typescript", "python"]
  }' | jq -r '.files[] | @json' | while read -r file; do
    path=$(echo "$file" | jq -r '.path')
    content=$(echo "$file" | jq -r '.content')
    mkdir -p "$(dirname "$path")"
    echo "$content" > "$path"
done

Generated Files:

api-reference/
├── index.mdx                    # API overview
├── authentication.mdx           # Auth guide
├── workflows/
│   ├── list-workflows.mdx
│   ├── get-workflow.mdx
│   ├── create-workflow.mdx
│   └── update-workflow.mdx
├── agents/
│   ├── list-agents.mdx
│   ├── invoke-agent.mdx
│   └── get-agent-status.mdx
└── errors.mdx                   # Error codes reference

Step 4: Add Interactive API Playground

Mintlify automatically generates an API playground from OpenAPI specs:

---
title: 'List Workflows'
api: 'GET /api/v1/workflows'
---

## Query Parameters

<ParamField query="status" type="string">
  Filter workflows by status: `active`, `inactive`, or `failed`
</ParamField>

## Response

<ResponseField name="workflows" type="array">
  Array of workflow objects
  
  <Expandable title="Workflow Object">
    <ResponseField name="id" type="string" required>
      Unique workflow identifier (UUID)
    </ResponseField>
    <ResponseField name="name" type="string" required>
      Human-readable workflow name
    </ResponseField>
    <ResponseField name="status" type="string" required>
      Current status: `active`, `inactive`, or `failed`
    </ResponseField>
  </Expandable>
</ResponseField>

**Request Example:**

<CodeGroup>
```bash cURL
curl https://control-plane.so1.io/api/v1/workflows?status=active \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```typescript TypeScript
const response = await fetch('https://control-plane.so1.io/api/v1/workflows?status=active', {
  headers: {
    'Authorization': `Bearer ${process.env.CONTROL_PLANE_API_KEY}`
  }
});
const workflows = await response.json();
```
</CodeGroup>

**Response Example:**

```json
{
  "workflows": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Webhook Processing Pipeline",
      "status": "active",
      "created_at": "2026-03-10T14:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 50
}
```

{
  "navigation": [
    {
      "group": "API Reference",
      "pages": [
        "api-reference/index",
        "api-reference/authentication",
        {
          "group": "Workflows",
          "pages": [
            "api-reference/workflows/list-workflows",
            "api-reference/workflows/get-workflow",
            "api-reference/workflows/create-workflow",
            "api-reference/workflows/update-workflow"
          ]
        },
        "api-reference/errors"
      ]
    }
  ]
}

Procedure 3: Create Operational Runbooks

Step 1: Define Runbook Scope

interface RunbookSpec {
  title: string;
  domain: string;
  procedures: {
    name: string;
    steps: number;
    estimated_time: string;
  }[];
  target_audience: string[];
  prerequisites: string[];
}

Step 2: Invoke Runbook Writer Agent

curl -X POST https://control-plane.so1.io/api/v1/agents/runbook-writer/generate \
  -H "Authorization: Bearer ${CONTROL_PLANE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "runbook_type": "operational",
    "domain": "incident_response",
    "title": "Incident Response Procedures",
    "procedures": [
      {
        "name": "Detect and Declare Incident",
        "description": "Initial detection, triage, and incident declaration",
        "steps": [
          "Monitor alerting channels",
          "Assess severity",
          "Declare incident via n8n workflow",
          "Create Slack incident channel",
          "Notify on-call engineer"
        ]
      },
      {
        "name": "Investigate Root Cause",
        "description": "Gather data, analyze logs, identify root cause",
        "steps": [
          "Check system metrics",
          "Review error logs",
          "Query database for anomalies",
          "Use triage-responder agent for analysis"
        ]
      },
      {
        "name": "Mitigate and Resolve",
        "description": "Apply fixes and restore service",
        "steps": [
          "Implement mitigation",
          "Verify resolution",
          "Update incident status"
        ]
      }
    ],
    "include_troubleshooting": true,
    "include_commands": true,
    "target_audience": ["sre", "devops", "on_call_engineers"]
  }' | jq '.'

Expected Response:

{
  "generation_id": "gen_2mP7nQzXy",
  "file_path": "runbooks/incident-response.mdx",
  "content": "---\ntitle: 'Incident Response Procedures'\ndescription: 'Complete incident lifecycle management'\nicon: 'siren'\n---\n\n## Overview\n\nThis runbook covers...",
  "procedures": 3,
  "steps": 12,
  "estimated_reading_time": "15 minutes"
}

Step 3: Review and Customize Runbook

Key elements to verify:

Prerequisites Section

Required access (API keys, service accounts)
Required tools (CLI commands, software)
Required knowledge (concepts, procedures)

Procedure Steps

Clear step-by-step instructions
Actual commands (not pseudocode)
Expected outputs
Decision points clearly marked

Verification Checklists

Success criteria after each procedure
Checklist items (✅ format)
Validation commands

Troubleshooting Section

Common issues in table format
Symptoms, root causes, resolutions
Links to related documentation

Related Resources

Step 4: Test Runbook Procedures

# Execute each procedure in a test environment
# Document any deviations or issues

# Example: Test incident declaration
curl -X POST https://n8n.so1.io/webhook/incident/declare \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Test Incident - Documentation Validation",
    "severity": "SEV4",
    "description": "Testing runbook procedures"
  }'

# Verify Slack channel created
# Verify notifications sent
# Document actual vs. expected behavior

Step 5: Publish Runbook

# Add to git
git add runbooks/incident-response.mdx

# Update mint.json
# (runbook-writer agent generates navigation updates)

# Commit and push
git commit -m "Add incident response runbook"
git push origin main

# Verify deployment
curl -s https://docs.so1.io/runbooks/incident-response | grep "Incident Response"

Procedure 4: Maintain Documentation Quality

Step 1: Run Documentation Audit

# Check for broken links
npx mintlify broken-links

# Validate MDX syntax
npx mintlify validate

# Check for outdated content
curl -X POST https://control-plane.so1.io/api/v1/agents/mintlify-author/audit \
  -H "Authorization: Bearer ${CONTROL_PLANE_API_KEY}" \
  -d '{"repository": "so1-io/so1-content"}' | jq '.outdated_pages'

Step 2: Update Outdated Content

# Identify pages not updated in 90+ days
find . -name "*.mdx" -mtime +90 -exec ls -lh {} \;

# Review and update content
# Re-generate with updated agent metadata
curl -X POST https://control-plane.so1.io/api/v1/agents/mintlify-author/regenerate \
  -H "Authorization: Bearer ${CONTROL_PLANE_API_KEY}" \
  -d '{
    "page_path": "agents/automation/workflow-architect.mdx",
    "update_reason": "Agent updated to v1.3.0",
    "preserve_custom_sections": true
  }'

Step 3: Review User Feedback

# Check Mintlify analytics for most-viewed pages
# Review feedback from Mintlify "Was this helpful?" widget
# Identify pages with high bounce rates

# Mintlify dashboard → Analytics → Page Views
# Mintlify dashboard → Feedback → Recent Feedback

Step 4: Continuous Improvement

Monthly Documentation Review:

Verification Checklist

After completing documentation operations, verify:

Troubleshooting

Issue	Symptoms	Root Cause	Resolution
MDX Syntax Error	Page doesn’t render, shows error	Invalid component syntax	Run `npx mintlify validate`, check component documentation
Broken Links	404 when clicking link	Incorrect file path or deleted page	Use `npx mintlify broken-links` to find and fix
Build Failure	Deployment fails	TypeScript errors, missing files	Check Mintlify dashboard build logs, fix errors
Navigation Not Updating	New pages don’t appear	mint.json not updated	Add page paths to `navigation` array in mint.json
API Playground Not Working	”Try it” button fails	Invalid OpenAPI spec	Validate spec with `npx @redocly/cli lint openapi.json`
Search Not Finding Content	Search returns no results	Content not indexed	Rebuild search index via Mintlify dashboard
Slow Page Load	Pages take >3s to load	Large images, unoptimized	Compress images, use Mintlify `<img>` component
Dark Mode Issues	Content unreadable in dark mode	Hardcoded colors	Use Mintlify theme colors (`text-primary`, etc.)

Detailed Troubleshooting: MDX Component Errors

# Common MDX issues:

# 1. Unclosed component tags
# ❌ Incorrect:
<Card title="Example">
Content here
# Missing </Card>

# ✅ Correct:
<Card title="Example">
  Content here
</Card>

# 2. Invalid prop types
# ❌ Incorrect:
<Card title={title} /> # Using JSX in MDX without proper escaping

# ✅ Correct:
<Card title="My Title" />

# 3. Component not imported
# ✅ Mintlify components are auto-imported:
# Card, CardGroup, Info, Warning, Tip, Check, etc.
# No manual imports needed

# Validate all MDX files:
npx mintlify validate --path .

Mintlify Author Agent

Documentation content generation

API Documenter Agent

OpenAPI specification generation

Runbook Writer Agent

Operational runbook creation

Mintlify Docs

Official Mintlify documentation

Best Practices

Content Writing

Write for scanners: Use headings, bullets, tables for easy scanning
Show, don’t tell: Provide code examples and screenshots
Use consistent terminology: Create a glossary for platform-specific terms
Keep it current: Review and update docs with each release
Test all examples: Ensure code snippets actually work

Mintlify Components

Use semantic components:
- <Info> for helpful tips
- <Warning> for important cautions
- <Tip> for best practices
- <Check> for checklists

Organize with CardGroups for related links:

<CardGroup cols={2}>
  <Card title="..." icon="..." href="...">
    Description
  </Card>
</CardGroup>

Use Tabs for alternatives:

<Tabs>
  <Tab title="cURL">
    ```bash
    curl ...
    ```
  </Tab>
  <Tab title="TypeScript">
    ```typescript
    fetch(...)
    ```
  </Tab>
</Tabs>

API Documentation

Document all endpoints: Even internal/beta endpoints
Provide realistic examples: Use actual data formats
Include error responses: Document all possible error codes
Show authentication: Clear examples of auth headers
Add rate limits: Document throttling policies

Runbook Standards

Use imperative mood: “Run the command”, not “The command should be run”
Provide actual commands: Full curl commands, not placeholders
Include expected outputs: Show what success looks like
Add troubleshooting: Common issues with resolutions
Link to related docs: Cross-reference agents, APIs, architecture

Runbooks

Domain Runbooks

Overview

Prerequisites

Procedure 1: Author Mintlify Documentation

Step 1: Plan Documentation Structure

Step 2: Invoke Mintlify Author Agent

Step 3: Review and Customize Generated Content

Step 4: Validate Documentation Quality

Step 5: Deploy Documentation

Procedure 2: Generate API Documentation

Step 1: Extract API Endpoints from Codebase

Step 2: Enhance API Specification

Step 3: Generate Mintlify API Reference Pages

Step 4: Add Interactive API Playground

Step 5: Update mint.json Navigation

Procedure 3: Create Operational Runbooks

Step 1: Define Runbook Scope

Step 2: Invoke Runbook Writer Agent

Step 3: Review and Customize Runbook

Step 4: Test Runbook Procedures

Step 5: Publish Runbook

Procedure 4: Maintain Documentation Quality

Step 1: Run Documentation Audit

Step 2: Update Outdated Content

Step 3: Review User Feedback

Step 4: Continuous Improvement

Verification Checklist

Troubleshooting

Detailed Troubleshooting: MDX Component Errors

Mintlify Author Agent

API Documenter Agent

Runbook Writer Agent

Mintlify Docs

Best Practices

Content Writing

Mintlify Components

API Documentation

Runbook Standards

Runbooks

Domain Runbooks

​Overview

​Prerequisites

​Procedure 1: Author Mintlify Documentation

​Step 1: Plan Documentation Structure

​Step 2: Invoke Mintlify Author Agent

​Step 3: Review and Customize Generated Content

​Step 4: Validate Documentation Quality

​Step 5: Deploy Documentation

​Procedure 2: Generate API Documentation

​Step 1: Extract API Endpoints from Codebase

​Step 2: Enhance API Specification

​Step 3: Generate Mintlify API Reference Pages

​Step 4: Add Interactive API Playground

​Step 5: Update mint.json Navigation

​Procedure 3: Create Operational Runbooks

​Step 1: Define Runbook Scope

​Step 2: Invoke Runbook Writer Agent

​Step 3: Review and Customize Runbook

​Step 4: Test Runbook Procedures

​Step 5: Publish Runbook

​Procedure 4: Maintain Documentation Quality

​Step 1: Run Documentation Audit

​Step 2: Update Outdated Content

​Step 3: Review User Feedback

​Step 4: Continuous Improvement

​Verification Checklist

​Troubleshooting

​Detailed Troubleshooting: MDX Component Errors

​Related Resources

Mintlify Author Agent

API Documenter Agent

Runbook Writer Agent

Mintlify Docs

​Best Practices

​Content Writing

​Mintlify Components

​API Documentation

​Runbook Standards

Overview

Prerequisites

Procedure 1: Author Mintlify Documentation

Step 1: Plan Documentation Structure

Step 2: Invoke Mintlify Author Agent

Step 3: Review and Customize Generated Content

Step 4: Validate Documentation Quality

Step 5: Deploy Documentation

Procedure 2: Generate API Documentation

Step 1: Extract API Endpoints from Codebase

Step 2: Enhance API Specification

Step 3: Generate Mintlify API Reference Pages

Step 4: Add Interactive API Playground

Step 5: Update mint.json Navigation

Procedure 3: Create Operational Runbooks

Step 1: Define Runbook Scope

Step 2: Invoke Runbook Writer Agent

Step 3: Review and Customize Runbook

Step 4: Test Runbook Procedures

Step 5: Publish Runbook

Procedure 4: Maintain Documentation Quality

Step 1: Run Documentation Audit

Step 2: Update Outdated Content

Step 3: Review User Feedback

Step 4: Continuous Improvement

Verification Checklist

Troubleshooting

Detailed Troubleshooting: MDX Component Errors

Related Resources

Best Practices

Content Writing

Mintlify Components

API Documentation

Runbook Standards