DealAgent documentation: user guide, playbook, and SDK reference

[kovtcharov]

Summary

Create comprehensive documentation for the DealAgent: a user-facing guide, a step-by-step playbook for building a price tracker, and SDK reference for the DealAgent tools and configuration.

Motivation

Every GAIA agent requires documentation (CLAUDE.md mandate). The DealAgent documentation also serves as a showcase for the Agent Hub — demonstrating how a practical, real-world agent is built and used.

Documentation Files

1. User Guide — docs/guides/deals.mdx

---
title: "Deal Finder & Price Tracker"
description: "Track prices, find deals, and get alerts — all running locally"
---

## Overview
## Quick Start
  - Getting API keys (Best Buy, SerpApi)
  - First product search: `gaia deals "laptop under $800"`
  - Adding to watchlist
  - Starting background monitoring

## Features
  - Product search across retailers
  - Price history tracking
  - Price drop alerts
  - Deal quality analysis
  - Price history charts

## Configuration
  - Environment variables
  - DealAgentConfig options
  - Notification setup (desktop, webhook)

## Examples
  - "Find the best deal on AirPods Pro"
  - "Track this TV and alert me under $500"
  - "Show me the price history for MacBook Pro"
  - "Is this a good time to buy a PS5?"

2. Playbook — docs/playbooks/deals.mdx

Step-by-step tutorial: "Build a price tracking agent"

• Why price tracking? (CamelCamelCamel use case)
• Setting up API keys
• Your first search query
• Understanding price history
• Setting up alerts
• Running background monitoring
• Customizing for your needs

3. SDK Reference — docs/sdk/agents/deals.mdx

---
title: "DealAgent SDK"
description: "API reference for the Deal Finder & Price Tracker agent"
---

## DealAgent Class
## DealAgentConfig
## Tools Reference
  - search_products
  - get_product_price
  - find_deals
  - compare_prices
  - add_to_watchlist / remove_from_watchlist / list_watchlist
  - show_price_history
  - analyze_deal
## Database Schema
## Notification Channels
## Extending the DealAgent

4. Update Existing Docs

• docs/docs.json — Add deals pages to navigation
• docs/reference/cli.mdx — Add gaia deals command reference
• docs/reference/faq.mdx — Add deals FAQ section

Acceptance Criteria

• docs/guides/deals.mdx — User guide with examples and screenshots
• docs/playbooks/deals.mdx — Step-by-step tutorial
• docs/sdk/agents/deals.mdx — SDK reference for all tools and config
• docs/docs.json updated with new pages in correct navigation sections
• docs/reference/cli.mdx updated with gaia deals commands
• All code examples tested and verified to work
• Links to API key registration pages included

Phase

Phase 4 — Distribution

Dependencies

• All Phase 1-3 issues (documents completed features)