Skip to main content
This guide clarifies what goes where in GAIA documentation and how to contribute.

​
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 ChatConfig 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 ChatSDK?” → 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