Skip to main content

​
Documentation Domain

The Documentation domain ensures that all features, APIs, and operational procedures are thoroughly documented for developers, operators, and end-users.

​
Overview

Documentation agents create Mintlify docs sites, generate OpenAPI specifications, and write operational runbooks that enable teams to effectively use and maintain the SO1 platform.
Use Documentation agents when you need to:
  • Create Mintlify documentation pages with MDX
  • Generate OpenAPI specs from Zod schemas
  • Write operational runbooks for incident response
  • Document APIs, features, and troubleshooting procedures
  • Maintain synchronization between code and documentation

​
Agents in This Domain

Mintlify Author

Creates Mintlify MDX docs with components and navigation

API Documenter

Generates OpenAPI 3.1 specs from Hono APIs and Zod schemas

Runbook Writer

Creates operational runbooks for incident response and maintenance

​
When to Use This Domain

Feature implementation complete, needs documentation
API endpoints require OpenAPI specification
Alerts need associated runbooks
New integration or feature needs user guides
Maintenance procedures need standardization
Incident response procedures need documentation
Not suitable for:
  • Auto-generating docs from comments alone (requires human review)
  • Real-time documentation updates (these are point-in-time)
  • Non-technical user manuals (focus is on developer/operator docs)

​
Common Patterns

​
Pattern 1: Feature Documentation Workflow

Workflow:
  1. API Documenter generates OpenAPI spec from Zod schemas
  2. Mintlify Author creates developer guides with code examples
  3. Documentation published to docs.so1.io

​
Pattern 2: Incident Readiness

Workflow:
  1. Runbook Writer analyzes alert and system architecture
  2. Creates step-by-step diagnosis and resolution procedures
  3. Defines escalation criteria and contacts
  4. Validates with tabletop exercise

​
Pattern 3: API Documentation Sync

Workflow:
  1. Code changes trigger documentation update
  2. API Documenter regenerates OpenAPI spec
  3. Mintlify Author updates API reference pages
  4. Changes reviewed and published

​
FORGE Stage Integration

AgentFORGE StageEntry GateExit Gate
Mintlify Author5 (VERIFY)Feature implementation completeMDX pages created, navigation updated
API Documenter5 (VERIFY)API endpoints implementedOpenAPI spec generated and validated
Runbook Writer5 (VERIFY)System architecture documentedRunbooks created and tested
All Documentation agents operate in the VERIFY stage, ensuring that implementations are properly documented and operationally ready.

​
Integration Points

​
Veritas Prompts

Documentation agents consume and produce Veritas prompts:
AgentConsumesProduces
Mintlify AuthorTechnical writing best practices, Mintlify component patternsDocumentation tasks
API DocumenterAPI documentation standards, OpenAPI best practicesDocumentation fragments
Runbook WriterRunbook structure, incident response patternsOperational tasks

​
Repositories

Documentation is distributed across multiple repositories:
  • so1-io/docs - Mintlify documentation site (primary)
  • so1-io/runbooks - Operational runbooks
  • so1-io/so1-control-plane-api - OpenAPI specs (embedded)
  • so1-io/so1-shared - Source of Zod schemas for API docs

​
Mintlify Platform

  • Target: docs.so1.io
  • Format: MDX pages with Mintlify components
  • Navigation: Structured in mint.json
  • Components: Card, Steps, Tabs, Accordion, CodeGroup, etc.

​
Best Practices

​
Technical Writing

1

Know Your Audience

Write for developers (API docs), operators (runbooks), or end-users (guides) with appropriate language and depth
2

Use Active Voice

“Click the button” instead of “The button should be clicked”
3

Provide Working Examples

All code examples should be tested and runnable
4

Link Related Content

Cross-reference related docs, APIs, and concepts

​
API Documentation

1

Generate from Source

Use Zod schemas as single source of truth for API documentation
2

Include Examples

Provide request/response examples for every endpoint
3

Document Errors

Show common error responses with codes and messages
4

Validate Specs

Use spectral or openapi-lint to validate OpenAPI specs

​
Operational Runbooks

1

Make Commands Copy-Pasteable

No manual substitution required - use environment variables
2

Include Expected Output

Show what success looks like after each step
3

Define Escalation Clearly

Specify when to escalate and to whom
4

Test with Dry Runs

Validate runbooks with tabletop exercises before incidents

​
Outputs and Artifacts

​
Mintlify Author

---
title: "Getting Started"
description: "Set up SO1 in under 5 minutes"
icon: "rocket"
---

# Getting Started

<Steps>
  <Step title="Create account">
    Visit console.so1.io and sign up with GitHub
  </Step>
  <Step title="Create organization">
    Set up your team workspace
  </Step>
</Steps>

​
API Documenter

openapi: 3.1.0
info:
  title: SO1 API
  version: 1.0.0
paths:
  /api/v1/workflows:
    get:
      summary: List workflows
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowList'

​
Runbook Writer

# Runbook: API High Error Rate

## Severity
- **Level**: P2 (High)
- **Impact**: API failures, workflow execution issues

## Diagnosis
1. Check error rate dashboard
2. Identify failing endpoints
3. Check dependencies (DB, Redis, n8n)

## Resolution
- Scenario A: Database issues → Restart DB
- Scenario B: Memory issues → Scale up
- Scenario C: Bad deployment → Rollback

Engineering Domain

Backend and frontend implementations that need documentation

DevOps Domain

CI/CD and deployment procedures documented by runbooks

Incident Domain

Uses runbooks during incident response

FORGE Stages

Documentation fits in VERIFY stage

​
Getting Started

1

Install Documentation Agents

Follow the Agent Installation Guide to add Documentation agents to OpenCode
2

Choose Your Agent

  • User-facing docs → Mintlify Author
  • API reference → API Documenter
  • Incident procedures → Runbook Writer
3

Invoke the Agent

Use the agent in your OpenCode chat or workflow
4

Review and Publish

Review generated documentation, test examples, and publish
Next Steps: