Skip to main content
This guide clarifies what goes where in GAIA documentation and how to contribute.
Contributing code or filing issues? See CONTRIBUTING.md for the general contribution guide, including the requirement that every pull request links a GitHub issue. This page covers documentation contributions only.

​
The Problem

Section names can be confusing:
  • “SDK Reference” in Documentation tab vs “SDKs” in Specifications tab - what’s the difference?
  • “User Guides” vs “Playbooks” - when to use which?
  • “Reference” vs “Specifications” - aren’t they the same?
This guide provides clear definitions and decision criteria.

​
Documentation Tab

​
User Guides (docs/guides/)

Definition: Task-oriented tutorials teaching users how to accomplish goals with GAIA features. Contains:
  • Step-by-step instructions
  • CLI commands users can run
  • Working Python code examples
  • Troubleshooting sections
When to use: User asks “How do I chat with PDF documents?” When NOT to use: User asks “What parameters does AgentConfig accept?” → That’s a Specification Example: docs/guides/chat.mdx

​
Playbooks (docs/playbooks/)

Definition: Multi-part tutorials for building agents from scratch, with deep explanations of why things work. Contains:
  • 3+ part series
  • Architecture diagrams (Mermaid)
  • “Under the Hood” explanations
  • Complete working code at the end
When to use: Teaching someone to BUILD a new agent type from scratch When NOT to use: Explaining how to USE an existing agent → That’s a Guide Example: docs/playbooks/chat-agent/

​
SDK Reference (docs/sdk/sdks/)

Definition: Quick code snippets for rapid development - “cheat sheets” developers copy-paste. Contains:
  • Import statements
  • Common usage patterns (5-10 lines each)
  • No step-by-step tutorials
  • Links to full specifications
When to use: Developer asks “What’s the quick way to do streaming chat?” When NOT to use: Developer asks “What are ALL the methods on AgentSDK?” → That’s a Specification Example: docs/sdk/sdks/chat.mdx

​
Specifications Tab

​
SDK Specifications (docs/spec/*-sdk.mdx, docs/spec/*-client.mdx)

Definition: Complete technical contracts for SDK modules - ALL methods, parameters, types, and internals. Contains:
  • Full API with every method signature
  • All parameters with types, defaults, descriptions
  • Implementation details and testing requirements
  • Extension points for contributors
When to use: Developer needs to know ALL methods on a class, or wants to extend the SDK When NOT to use: Developer just wants to quickly use the SDK → That’s SDK Reference or a Guide Example: docs/spec/llm-client.mdx

​
Infrastructure Specifications (docs/spec/api-server.mdx, docs/spec/mcp-*.mdx)

Definition: Technical architecture of GAIA’s backend systems - servers, bridges, registries. Contains:
  • Functional/Non-Functional Requirements
  • Complete Pydantic schemas
  • Request/response formats
  • Internal implementation logic
When to use: Developer needs to understand or extend backend infrastructure When NOT to use: User just wants to start the API server → That’s Reference

​
Reference Tab

​
CLI Reference (docs/reference/cli.mdx)

Definition: Complete documentation of all CLI commands, flags, and options. When to use: User asks “What flags does gaia chat accept?”

​
API Reference (docs/reference/api.mdx)

Definition: User-facing guide for using the REST API server. When to use: User asks “How do I use the API server?” (not “How is it built?” - that’s a Specification)

​
Comparison Tables

​
SDK Reference vs SDK Specification

AspectSDK Reference (docs/sdk/sdks/)SDK Specification (docs/spec/)
PurposeQuick usage examplesComplete technical contract
Length~100-200 lines~800-1400 lines
ContentCopy-paste snippetsFull API signatures, internals
AudienceDevelopers USING the SDKDevelopers EXTENDING the SDK

​
Guides vs Playbooks

AspectUser Guides (docs/guides/)Playbooks (docs/playbooks/)
PurposeUSE pre-built featuresBUILD agents from scratch
FormatSingle page tutorialMulti-part series (3+ parts)
OutputUser accomplishes a taskUser builds a complete agent

​
Reference vs Specifications

AspectReference (docs/reference/)Specifications (docs/spec/)
FocusUser-facing toolsInternal architecture
AudienceUsers and operatorsSDK developers and contributors

​
Decision Tree

“I want to document…”
  1. How to USE a feature → User Guide (docs/guides/)
  2. How to BUILD an agent from scratch → Playbook (docs/playbooks/)
  3. Quick code snippets for developers → SDK Reference (docs/sdk/sdks/)
  4. Complete API contract (all methods) → Specification (docs/spec/)
  5. CLI commands and flags → CLI Reference (docs/reference/cli.mdx)
  6. Backend architecture → Infrastructure Spec (docs/spec/)

​
Contributing Process

​
Step 1: Identify the Right Location

Use the decision tree above to determine where your content belongs.

​
Step 2: Create Your File

Create a .mdx file in the appropriate directory with frontmatter: 
---
title: "Your Page Title"
description: "One-line description"
icon: "icon-name"
---

​
Step 3: Update Navigation

Add your page to docs/docs.json in the appropriate tab and group.

​
Step 4: Submit a Pull Request

git checkout -b docs/your-feature
git add docs/
git commit -m "docs: add [description]"
git push origin docs/your-feature

​
Style Guidelines

  • Use active voice and second person (“you”)
  • Include working code examples
  • Add source code links at the top
  • Include license footer at the bottom
  • Cross-link to related documentation

​
Review Checklist

  • Content is in the correct section (use decision tree)
  • Frontmatter has title and description
  • Added to docs/docs.json
  • Code examples are complete and working
  • License footer included