Documentation - Ensemble Edge

The docs/ directory is a first-class component directory in Conductor that serves interactive API documentation. It auto-generates OpenAPI 3.1 specifications from your ensembles and agents, supports markdown documentation pages with Handlebars templating, and serves them through multiple documentation UIs.

Features

First-class component directory - Just like agents/ and ensembles/, docs/ is a dedicated directory
Auto-generated OpenAPI specs - Scans your ensembles and agents to create accurate API docs
Markdown documentation - Write .md files with frontmatter for custom pages
Multiple UI frameworks - Stoplight Elements, Redoc, Swagger UI, Scalar, RapiDoc
Custom branding - Add your logo, colors, and styling
Built-in caching - Fast documentation serving with optional KV caching
Authentication - Public, authenticated, or admin-only documentation
Handlebars templating - Dynamic content with variables

New to docs? Check out Your First Documentation for a comprehensive step-by-step guide.

Directory Structure

your-project/
├── docs/
│   ├── getting-started.md  # Markdown page (auto-discovered)
│   ├── authentication.md   # Another page
│   └── guides/
│       ├── quickstart.md
│       └── advanced.md
├── ensembles/              # docs-serve ensemble handles routing
├── agents/
└── conductor.config.ts

How It Works

Documentation is served via the built-in docs-serve ensemble which handles HTTP routing automatically. Your markdown files in docs/ are auto-discovered at build time.

Basic Setup

Create markdown files in docs/:

mkdir -p docs
echo "# Getting Started\n\nWelcome to the API!" > docs/getting-started.md

Start the dev server:

ensemble conductor start

Access your docs:

curl http://localhost:8787/docs

Customizing Documentation

To customize your documentation, create a custom docs ensemble. This is where you configure themes, navigation, and UI framework. Create ensembles/docs-custom.yaml:

name: docs-custom
description: Customized documentation

trigger:
  - type: http
    paths:
      - path: /docs
        methods: [GET]
      - path: /docs/:slug
        methods: [GET]
      - path: /docs/openapi.json
        methods: [GET]
    public: true

flow:
  - name: render
    agent: docs
    config:
      title: My API Documentation
      basePath: /docs
      ui: stoplight
      theme:
        primaryColor: '#3B82F6'
        darkMode: true

output:
  _raw: ${render.output}

Configuration Reference

All configuration is passed via the ensemble’s flow[].config:

Route Configuration

Control where and how docs are served via the trigger:

trigger:
  - type: http
    path: /docs         # URL path (default: /docs)
    methods: [GET]
    public: true        # true = public, false = requires auth

Change the path:

trigger:
  - type: http
    path: /api/reference  # Now served at /api/reference

Require authentication:

trigger:
  - type: http
    path: /docs/internal
    public: false       # Requires authentication (Bearer token, API key, etc.)

The public: false setting enforces authentication. Conductor validates Bearer tokens or API keys from request headers automatically.

UI Framework

Choose your preferred documentation UI:

ui: stoplight  # Options: stoplight, redoc, swagger, scalar, rapidoc

UI	Description
`stoplight`	Modern, interactive Stoplight Elements (default)
`redoc`	Clean, mobile-friendly Redoc
`swagger`	Classic Swagger UI
`scalar`	Beautiful, customizable Scalar
`rapidoc`	Fast, lightweight RapiDoc

Theme & Branding

Customize the appearance:

title: "My API Documentation"
description: "Complete API reference"

theme:
  primaryColor: '#007bff'
  darkMode: true
  customCss: |
    body {
      font-family: 'Inter', sans-serif;
    }

Control how documentation pages are organized:

nav:
  # Simple ordering (slugs or glob patterns)
  order:
    - getting-started
    - authentication
    - guides/*           # All pages in guides/
    - api/**             # Recursive glob

  # Hide specific pages
  hide:
    - internal-notes
    - drafts/*

  # Reserved sections (auto-generated)
  showReserved:
    agents: true         # Show agents section
    ensembles: true      # Show ensembles section
    api: true            # Show OpenAPI reference

  reservedPosition: bottom  # top | bottom

  reservedLabels:
    agents: "AI Agents"
    ensembles: "Workflows"
    api: "API Reference"

Organize pages into collapsible groups:

nav:
  groups:
    - title: Getting Started
      icon: 🚀
      items:
        - overview
        - quickstart
        - installation

    - title: Guides
      icon: 📖
      items:
        - guides/*        # Glob pattern

    - title: API Reference
      icon: 📚
      items:
        - api/*
      collapsed: true     # Collapsed by default

Caching

Enable caching for better performance:

cache:
  enabled: true
  ttl: 300  # seconds

AI Enhancement

Use AI to improve documentation descriptions:

ai:
  enabled: true
  model: '@cf/meta/llama-3.1-8b-instruct'
  provider: cloudflare  # cloudflare | openai | anthropic
  temperature: 0.3

Server URLs

Specify API server URLs in OpenAPI spec:

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging.example.com/v1
    description: Staging

Content Filtering

Control which endpoints appear in docs:

include:
  - /api/v1/*
  - /public/*

exclude:
  - /api/v1/internal/*
  - /admin/*

Writing Documentation Pages

Markdown with Frontmatter

Create .md files in the docs/ directory:

---
title: Getting Started
description: Quick start guide for the API
order: 1
icon: 🚀
---

# Getting Started

Welcome to the API! This guide will help you make your first call.

## Base URL

\`\`\`
https://api.example.com/v1
\`\`\`

## Authentication

Include your API key in the header:

\`\`\`bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.example.com/v1/users
\`\`\`

Frontmatter Options

Field	Type	Description
`title`	string	Page title (used in nav and header)
`description`	string	Page description (for SEO/preview)
`order`	number	Navigation order (lower = first)
`hidden`	boolean	Hide from navigation
`icon`	string	Icon for navigation (emoji or icon name)
`category`	string	Category for organization

Handlebars Templating

Use Handlebars syntax for dynamic content:

---
title: Getting Started
---

# Welcome to {{projectName}}

Current version: {{version}}

{{#if showAdvanced}}
## Advanced Features
...
{{/if}}

Variables are passed during rendering from your configuration.

Reserved Routes

These routes are automatically generated:

Route	Description
`/docs/agents`	Auto-generated list of all agents
`/docs/ensembles`	Auto-generated list of all ensembles
`/docs/api`	OpenAPI interactive reference
`/docs/openapi.json`	OpenAPI spec in JSON format
`/docs/openapi.yaml`	OpenAPI spec in YAML format

Control visibility in your docs ensemble config:

config:
  nav:
    showReserved:
      agents: true
      ensembles: true
      api: true

Complete Example

Create ensembles/docs-complete.yaml:

name: docs-complete
description: Complete API Documentation

trigger:
  - type: http
    paths:
      - path: /docs
        methods: [GET]
      - path: /docs/:slug
        methods: [GET]
      - path: /docs/openapi.json
        methods: [GET]
      - path: /docs/openapi.yaml
        methods: [GET]
    public: true

flow:
  - name: render
    agent: docs
    config:
      title: MyApp API Documentation
      basePath: /docs
      ui: scalar
      theme:
        primaryColor: '#1a73e8'
        darkMode: true
      nav:
        groups:
          - title: Getting Started
            icon: 🚀
            items:
              - getting-started
              - authentication
              - quickstart
          - title: Guides
            icon: 📖
            items:
              - guides/*
          - title: Reference
            icon: 📚
            items:
              - api
              - agents
              - ensembles
            collapsed: true
        hide:
          - internal-notes
          - drafts/*
      servers:
        - url: https://api.myapp.com/v1
          description: Production
        - url: http://localhost:8787
          description: Development
      cache:
        enabled: true
        ttl: 600
      ai:
        enabled: true
        model: '@cf/meta/llama-3.1-8b-instruct'

output:
  _raw: ${render.output}

Global Configuration

You can also configure docs globally in conductor.config.ts:

// conductor.config.ts
import { defineConfig } from '@anthropic/conductor'

export default defineConfig({
  docs: {
    title: 'My API Documentation',
    ui: 'stoplight',

    theme: {
      primaryColor: '#3B82F6',
      darkMode: true,
    },

    auth: {
      requirement: 'public',
    },

    cache: {
      enabled: true,
      ttl: 300,
    },

    ai: {
      enabled: true,
      model: '@cf/meta/llama-3.1-70b-instruct',
      provider: 'cloudflare',
    },
  },
})

Settings in your custom docs ensemble override global configuration.

Accessing Documentation

# Interactive HTML documentation
GET /docs

# Specific documentation page
GET /docs/getting-started
GET /docs/authentication

# OpenAPI specification
GET /docs/openapi.yaml
GET /docs/openapi.json

# Auto-generated sections
GET /docs/agents
GET /docs/ensembles
GET /docs/api

Best Practices

Organization

docs/
├── getting-started.md     # Entry point (auto-discovered)
├── authentication.md      # Core concepts
├── guides/
│   ├── quickstart.md
│   └── advanced.md
└── reference/
    └── errors.md

Security

Use authentication for sensitive documentation
Filter endpoints with include/exclude in config
Separate docs ensembles for different audiences

# Public docs ensemble
name: docs-public
trigger:
  - type: http
    path: /docs/public
    public: true

flow:
  - agent: docs
    config:
      include:
        - /api/v1/public/*

# Internal docs ensemble
name: docs-internal
trigger:
  - type: http
    path: /docs/internal
    public: false  # Requires auth

flow:
  - agent: docs
    config:
      include:
        - /api/v1/*

Performance

Enable caching for production
Use CDN through Cloudflare
Minimize custom CSS

cache:
  enabled: true
  ttl: 3600  # 1 hour

Troubleshooting

Docs Not Showing

Verify docs/ directory exists with at least one .md file
Rebuild the project: pnpm run build
Review logs for errors:
npx wrangler tail

Authentication Issues

Verify auth configuration

Test with correct headers:

curl -H "Authorization: Bearer TOKEN" http://localhost:8787/docs

Pages Not Appearing

Check frontmatter syntax is valid
Verify file extension is .md
Check hide config doesn’t exclude the page

Next Steps

Your First Documentation

Step-by-step guide to setting up docs

Agents Overview

Learn about creating agents

Ensembles

Orchestrate multi-agent workflows

Security & Authentication

Secure your documentation

​Features

​Directory Structure

​How It Works

​Basic Setup

​Customizing Documentation

​Configuration Reference

​Route Configuration

​UI Framework

​Theme & Branding

​Navigation Configuration

​Navigation Groups

​Caching

​AI Enhancement

​Server URLs

​Content Filtering

​Writing Documentation Pages

​Markdown with Frontmatter

​Frontmatter Options

​Handlebars Templating

​Reserved Routes

​Complete Example

​Global Configuration

​Accessing Documentation

​Best Practices

​Organization

​Security

​Performance

​Troubleshooting

​Docs Not Showing

​Authentication Issues

​Pages Not Appearing

​Next Steps

Your First Documentation

Agents Overview

Ensembles

Security & Authentication

Features

Directory Structure

How It Works

Basic Setup

Customizing Documentation

Configuration Reference

Route Configuration

UI Framework

Theme & Branding

Navigation Configuration

Navigation Groups

Caching

AI Enhancement

Server URLs

Content Filtering

Writing Documentation Pages

Markdown with Frontmatter

Frontmatter Options

Handlebars Templating

Reserved Routes

Complete Example

Global Configuration

Accessing Documentation

Best Practices

Organization

Security

Performance

Troubleshooting

Docs Not Showing

Authentication Issues

Pages Not Appearing

Next Steps