Your First Documentation

Estimated Time: 10-15 minutes Prerequisites: Working Conductor 1.8.1+ project

What You’ll Learn

By the end of this guide, you’ll understand how to:

📖 Auto-generate API documentation from your code
🔐 Control documentation access (public, authenticated, admin)
🔍 Add semantic search to your docs
✍️ Use AI to write better documentation
🔄 Keep docs in sync with code changes
📊 Deploy documentation to production

Understanding Documentation in Conductor

What’s the Difference?

Docs (plural) = The infrastructure

The agents in agents/docs/ that generate documentation
Production tools you configure and keep
Part of your application infrastructure

Documentation (singular) = The output

The actual API docs your users read
Generated HTML/JSON/Markdown
Served at endpoints like /docs-public

Think of it like:

Docs agents = Your documentation factory 🏭
Documentation = The products it manufactures 📄

Step 1: Verify Your Setup

Check What’s Already There

Conductor 1.8.1 includes documentation agents by default:

ls -la agents/docs/

# You should see:
# docs-simple.yaml
# docs-admin.yaml
# docs-authenticated.yaml
# docs-public.yaml
# docs-search/
# docs-writer/

These are production-ready tools, not examples to delete!

Test the Simplest Docs Agent

Start your dev server:

npm run dev

Visit the documentation endpoint:

curl http://localhost:8787/docs-simple

# Or open in browser:
# http://localhost:8787/docs-simple

What you should see: Auto-generated documentation of your API endpoints!

Step 2: Configure Your First Documentation

Choose Your Documentation Type

Public APIs
Authenticated APIs
Admin-Only

# agents/docs/docs-public.yaml
name: docs-public
operation: docs
description: Public-facing API documentation

auth: none  # No authentication required

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

exclude:
  - /admin/*
  - /internal/*

Customize Appearance

# agents/docs/docs-public.yaml
name: docs-public
operation: docs

metadata:
  title: "My API Documentation"
  version: "1.0"
  description: "Complete API reference for MyApp"
  contact: api@myapp.com

style:
  theme: dark  # or: light
  primary_color: "#007bff"
  logo: "/assets/logo.png"

Test Your Configuration

# Start dev server
npm run dev

# Visit your configured docs
curl http://localhost:8787/docs-public

# Or in browser with pretty formatting:
open http://localhost:8787/docs-public

Step 3: Add AI-Powered Documentation Writing

This step is optional but recommended for better documentation quality.

Why Use AI for Docs?

The docs-writer agent can:

Analyze your code structure
Write clear, helpful descriptions
Generate usage examples
Maintain consistent style
Update docs as code changes

Enable Workers AI

First, ensure Workers AI is bound in wrangler.toml:

# wrangler.toml
[ai]
binding = "AI"

Configure the AI Writer

# agents/docs/docs-writer/agent.yaml
name: docs-writer
operation: think
model: @cf/meta/llama-3.1-8b-instruct

description: |
  AI-powered documentation generator that creates clear,
  helpful API documentation from your codebase.

schema:
  input:
    codebase_path: string
    style: string  # conversational, technical, beginner-friendly
    include_examples: boolean
  output:
    markdown: string
    html: string

Create a Documentation Ensemble

Automate doc generation with an ensemble:

# ensembles/auto-docs.yaml
name: auto-docs
description: Automatically generate and update documentation

flow:
  # 1. Analyze codebase and generate docs
  - agent: docs-writer
    input:
      codebase_path: ./src
      style: ${input.style || "conversational"}
      include_examples: true

  # 2. Format and save
  - agent: docs-formatter
    input:
      markdown: ${docs-writer.output.markdown}
      format: html

output:
  markdown: ${docs-writer.output.markdown}
  html: ${docs-formatter.output.html}
  metadata:
    generated_at: ${timestamp}
    agent_used: docs-writer

Use the AI Writer

# Generate docs via API
curl -X POST http://localhost:8787/ensemble/auto-docs \
  -H 'Content-Type: application/json' \
  -d '{
    "style": "conversational"
  }'

Step 4: Add Semantic Search

This step is optional and requires Vectorize binding.

Why Add Search?

The docs-search agent enables:

Semantic search (understands meaning, not just keywords)
Fuzzy matching (“how to athenticate” still finds “authentication”)
Relevance ranking
Better user experience for large docs

Enable Vectorize

Add Vectorize binding to wrangler.toml:

# wrangler.toml
[[vectorize]]
binding = "VECTORIZE"
index_name = "docs-index"
dimensions = 768
metric = "cosine"

Configure Search Agent

# agents/docs/docs-search/agent.yaml
name: docs-search
operation: data
description: Semantic search for documentation

vectorize: true

schema:
  input:
    query: string
    limit: number
    filters: object?
  output:
    results: array
    count: number

Index Your Documentation

# Index docs (one-time setup)
curl -X POST http://localhost:8787/docs-search/index \
  -H 'Content-Type: application/json' \
  -d '{
    "source": "/docs-public",
    "reindex": true
  }'

Search Your Docs

# Search via API
curl -X POST http://localhost:8787/docs-search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "how to authenticate",
    "limit": 10
  }'

# Response:
{
  "results": [
    {
      "title": "Authentication Guide",
      "excerpt": "Use Bearer tokens...",
      "url": "/docs/auth",
      "relevance": 0.94
    }
  ],
  "count": 10
}

Step 5: Automate Documentation Updates

Keep Docs in Sync with Code

Git Pre-commit Hook
CI/CD Pipeline
Scheduled Updates

# .git/hooks/pre-commit
#!/bin/bash

echo "Updating documentation..."
npm run generate-docs

# Add updated docs to commit
git add docs/

NPM Scripts

Add to package.json:

{
  "scripts": {
    "generate-docs": "node scripts/generate-docs.js",
    "deploy-docs": "wrangler deploy",
    "docs:dev": "wrangler dev",
    "docs:preview": "wrangler pages dev"
  }
}

Step 6: Deploy to Production

Build Documentation

# Generate production docs
npm run generate-docs

# Build project
npm run build

Deploy with Wrangler

# Deploy to Cloudflare Workers
npm run deploy

# Your docs will be available at:
# https://your-app.workers.dev/docs-public
# https://your-app.workers.dev/docs-authenticated
# https://your-app.workers.dev/docs-admin

Custom Domain (Optional)

# wrangler.toml
routes = [
  { pattern = "docs.myapp.com/*", zone_name = "myapp.com" }
]

Now accessible at:

https://docs.myapp.com/public
https://docs.myapp.com/authenticated
https://docs.myapp.com/admin

Common Patterns & Use Cases

Multiple API Versions

agents/docs/
├── docs-v1-public.yaml      # /api/v1/docs
├── docs-v1-authenticated.yaml
├── docs-v2-public.yaml      # /api/v2/docs
└── docs-v2-authenticated.yaml

Each config:

name: v2-public
operation: docs
path: /api/v2/docs
include:
  - /api/v2/*

Separate Customer & Partner Docs

# agents/docs/docs-customer.yaml
name: customer-docs
operation: docs
auth: none
include: [/api/public/*]
style:
  branding: customer

# agents/docs/docs-partner.yaml
name: partner-docs
operation: docs
auth: partner-api-key
include: [/api/partner/*]
style:
  branding: partner

Internal + External Docs

# agents/docs/docs-external.yaml
name: external-docs
operation: docs
auth: none
include:
  - /api/v1/*
exclude:
  - /api/v1/internal/*
  - /api/v1/admin/*

# agents/docs/docs-internal.yaml
name: internal-docs
operation: docs
auth: employee
include:
  - /api/v1/*
  - /internal/*

Troubleshooting

Docs Not Showing

Problem: /docs-simple returns 404Solutions:

Check agent is registered:

npm run dev
# Look for "docs-simple" in agent list

Verify agent name matches route:

name: docs-simple  # Serves at /docs-simple

Check operation: docs is set correctly
Review logs for errors:
```
npm run dev | grep docs
```

Authentication Issues

Problem: Can’t access authenticated docsSolutions:

Configure auth in conductor.config.ts:

export default {
  auth: {
    type: 'bearer',
    required: true
  }
};

Test with auth header:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     http://localhost:8787/docs-authenticated

Check auth middleware is registered

AI Writer Not Working

Problem: docs-writer agent failsSolutions:

Verify Workers AI binding:
```
[ai]
binding = "AI"
```
Check model availability in your region
Review AI usage limits:
```
wrangler ai usage
```
Test with simpler input

Search Not Finding Results

Problem: docs-search returns no resultsSolutions:

Verify Vectorize binding configured
Check index exists:
```
wrangler vectorize list
```

Reindex documentation:

curl -X POST http://localhost:8787/docs-search/reindex

Test with exact matches first

Best Practices

Documentation Maintenance

✅ Do:

Update docs when API changes
Version your documentation
Include code examples
Test all examples work
Keep docs and code in sync

❌ Don’t:

Manually write docs that can be auto-generated
Mix different API versions in same docs
Forget to update docs after code changes
Expose internal endpoints in public docs

Security

✅ Do:

Separate public/authenticated/admin docs
Sanitize examples (remove real API keys)
Rate limit documentation endpoints
Log documentation access
Review docs for sensitive information

❌ Don’t:

Expose admin endpoints publicly
Include real credentials in examples
Skip authentication on sensitive docs
Allow unlimited doc generation requests

Performance

✅ Do:

Cache generated documentation
Use CDN for static docs
Lazy-load large documentation sets
Index incrementally
Monitor generation times

❌ Don’t:

Generate docs on every request
Load entire codebase for each doc
Skip caching strategies
Ignore performance metrics

Next Steps

Level Up Your Docs

Add Interactive Examples
- Include API playground
- Live request/response testing
- Code generators
Integrate with CI/CD
- Auto-generate on deploy
- Preview docs for PRs
- Validate doc completeness
Add Analytics
- Track most-viewed docs
- Monitor search queries
- Identify documentation gaps
Multilingual Docs
- Use AI to translate
- Maintain multiple versions
- Auto-detect user language
Advanced Search
- Filters by category
- Related documentation
- Suggested docs based on history

Summary

You’ve learned how to:

✅ Use Conductor’s built-in documentation agents
✅ Configure public, authenticated, and admin docs
✅ Add AI-powered doc generation
✅ Enable semantic search
✅ Automate documentation updates
✅ Deploy docs to production

The agents/docs/ directory isn’t just examples - it’s production infrastructure for maintaining great API documentation with minimal effort!

docs Operation Reference - Complete configuration reference and advanced features
Your First Agent - Build custom agents
Your First Ensemble - Orchestrate workflows
Authentication & Authorization - Secure your docs
Deploying to Production - Go live

Conductor

Getting Started

Core Concepts

Building

Components

Operations Reference

Pre-built Agents Reference

Playbooks

Reference

​What You’ll Learn

​Understanding Documentation in Conductor

​What’s the Difference?

​Step 1: Verify Your Setup

​Check What’s Already There

​Test the Simplest Docs Agent

​Step 2: Configure Your First Documentation

​Choose Your Documentation Type

​Customize Appearance

​Test Your Configuration

​Step 3: Add AI-Powered Documentation Writing

​Why Use AI for Docs?

​Enable Workers AI

​Configure the AI Writer

​Create a Documentation Ensemble

​Use the AI Writer

​Step 4: Add Semantic Search

​Why Add Search?

​Enable Vectorize

​Configure Search Agent

​Index Your Documentation

​Search Your Docs

​Step 5: Automate Documentation Updates

​Keep Docs in Sync with Code

​NPM Scripts

​Step 6: Deploy to Production

​Build Documentation

​Deploy with Wrangler

​Custom Domain (Optional)

​Common Patterns & Use Cases

​Multiple API Versions

​Separate Customer & Partner Docs

​Internal + External Docs

​Troubleshooting

​Best Practices

​Documentation Maintenance

​Security

​Performance

​Next Steps

​Level Up Your Docs

​Summary

​Related Guides

What You’ll Learn

Understanding Documentation in Conductor

What’s the Difference?

Step 1: Verify Your Setup

Check What’s Already There

Test the Simplest Docs Agent

Step 2: Configure Your First Documentation

Choose Your Documentation Type

Customize Appearance

Test Your Configuration

Step 3: Add AI-Powered Documentation Writing

Why Use AI for Docs?

Enable Workers AI

Configure the AI Writer

Create a Documentation Ensemble

Use the AI Writer

Step 4: Add Semantic Search

Why Add Search?

Enable Vectorize

Configure Search Agent

Index Your Documentation

Search Your Docs

Step 5: Automate Documentation Updates

Keep Docs in Sync with Code

NPM Scripts

Step 6: Deploy to Production

Build Documentation

Deploy with Wrangler

Custom Domain (Optional)

Common Patterns & Use Cases

Multiple API Versions

Separate Customer & Partner Docs

Internal + External Docs

Troubleshooting

Best Practices

Documentation Maintenance

Security

Performance

Next Steps

Level Up Your Docs

Summary

Related Guides