ajarbot/docs/README.md

# Ajarbot Documentation

Complete documentation for Ajarbot - a lightweight, cost-effective AI agent framework.

## Quick Navigation

### Getting Started (Start Here)

| Document | Description | Time to Read |
|----------|-------------|--------------|
| [Quick Start Guide](QUICKSTART.md) | 30-second setup and basic agent usage | 5 min |
| [Complete Setup Guide](../SETUP.md) | Comprehensive setup with API keys, config, troubleshooting | 10 min |

### Core Systems

| Document | Description | Best For |
|----------|-------------|----------|
| [Pulse & Brain Architecture](PULSE_BRAIN.md) | Cost-effective monitoring (92% savings) with Quick Start | Production monitoring, homelab |
| [Memory System](README_MEMORY.md) | SQLite-based memory management | Understanding context/memory |
| [Scheduled Tasks](SCHEDULED_TASKS.md) | Cron-like task scheduling | Daily briefings, reports |

### Platform Integration

| Document | Description | Best For |
|----------|-------------|----------|
| [Adapters Guide](README_ADAPTERS.md) | Multi-platform messaging (Slack, Telegram) | Running bots on chat platforms |
| [Skills Integration](SKILLS_INTEGRATION.md) | Claude Code skills from messaging platforms | Advanced bot capabilities |

### Configuration

| Document | Description | Best For |
|----------|-------------|----------|
| [Control & Configuration](CONTROL_AND_CONFIGURATION.md) | Configuration management | Customizing behavior |
| [Windows Deployment](WINDOWS_DEPLOYMENT.md) | Complete Windows setup guide | Windows users |

---

> **⚠️ Note on Heartbeat System**: The Heartbeat monitoring system is legacy and disabled by default. Use **Pulse & Brain** instead for 92% cost savings. Heartbeat documentation has been removed - see [PULSE_BRAIN.md](PULSE_BRAIN.md) for the recommended approach.

## Learning Paths

### Path 1: Simple Agent (10 minutes)

Perfect for quick prototypes or single-user use:

1. Read [Quick Start Guide](QUICKSTART.md)
2. Run `example_usage.py`
3. Explore [Memory System](README_MEMORY.md)

**What you'll learn:**
- Basic agent setup
- Memory operations
- Task management
- Model switching

### Path 2: Multi-Platform Bot (20 minutes)

For running bots on Slack, Telegram, or both:

1. Read [Quick Start Guide](QUICKSTART.md)
2. Read [Adapters Guide](README_ADAPTERS.md)
3. Run `bot_runner.py --init`
4. Configure platforms in `config/adapters.local.yaml`
5. Run `bot_runner.py`

**What you'll learn:**
- Platform adapter setup
- Multi-platform message routing
- User mapping across platforms
- Custom preprocessors/postprocessors

### Path 3: Production Monitoring (20 minutes)

For cost-effective production deployments:

1. Read [Pulse & Brain Architecture](PULSE_BRAIN.md) - includes Quick Start section
2. Run `example_bot_with_pulse_brain.py`
3. Create custom pulse checks
4. Configure custom brain tasks

**What you'll learn:**
- Pulse checks (zero-cost monitoring)
- Conditional brain tasks (only when needed)
- Scheduled brain tasks (daily summaries)
- Cost optimization (92% savings vs traditional monitoring)

### Path 4: Advanced Features (45 minutes)

For full-featured production bots:

1. Complete Path 2 and Path 3
2. Read [Scheduled Tasks](SCHEDULED_TASKS.md)
3. Read [Skills Integration](SKILLS_INTEGRATION.md)
4. Run `example_bot_with_skills.py`
5. Create custom skills

**What you'll learn:**
- Task scheduling with cron syntax
- Skills from messaging platforms
- Custom skill creation
- Security best practices

## Document Summaries

### QUICKSTART.md
30-second setup guide covering:
- Installation (pip install)
- Basic agent usage
- Memory operations
- Task tracking
- Context retrieval

**Key takeaway:** Get an agent running with memory in under a minute.

### PULSE_BRAIN.md
Comprehensive guide to the Pulse & Brain architecture:
- Quick Start section for immediate setup
- Why continuous polling is expensive ($0.48/day)
- How Pulse & Brain saves 92% ($0.04/day)
- Comparison with traditional monitoring (Heartbeat)
- Default pulse checks and brain tasks
- Custom configuration examples
- Real-world use cases (homelab, Docker monitoring)

**Key takeaway:** Run proactive monitoring at 1/10th the cost with Quick Start included.

### README_ADAPTERS.md
Multi-platform adapter system:
- Architecture overview
- Slack setup (Socket Mode)
- Telegram setup (polling)
- User mapping across platforms
- Adding new adapters
- Comparison with OpenClaw

**Key takeaway:** Run one bot on multiple platforms simultaneously.

### SKILLS_INTEGRATION.md
Claude Code skills in messaging platforms:
- Architecture overview
- Enabling skills in bots
- Creating custom skills
- Security best practices
- Skill arguments and metrics

**Key takeaway:** Invoke local Claude Code skills from Slack/Telegram.

### SCHEDULED_TASKS.md
Cron-like task scheduling:
- Task scheduler setup
- Schedule syntax (daily, weekly, cron)
- Recurring vs one-time tasks
- Task callbacks and error handling
- Multi-platform task routing

**Key takeaway:** Schedule recurring bot activities (reports, briefings, etc.).

### README_MEMORY.md
SQLite-based memory system:
- Memory architecture
- SOUL (personality) management
- User preferences
- Task system
- Full-text search (FTS5)
- Conversation history

**Key takeaway:** Automatic context loading with fast retrieval.

### CONTROL_AND_CONFIGURATION.md
Configuration management:
- Configuration file structure
- Environment variables
- Adapter configuration
- Pulse & Brain configuration
- Security considerations

**Key takeaway:** Centralized configuration for all components.

## Common Questions

### Q: Which monitoring system should I use?

**A:** Use **Pulse & Brain** for production. It's 92% cheaper and more flexible.

- **Pulse & Brain**: ~$1-2/month (recommended)
- **Heartbeat**: ~$15/month (legacy, disabled by default)

See [PULSE_BRAIN.md](PULSE_BRAIN.md) for details including comparison and migration guide.

### Q: Can I run my bot on multiple platforms?

**A:** Yes! See [Adapters Guide](README_ADAPTERS.md).

Example: Run the same bot on Slack and Telegram simultaneously with unified memory.

### Q: How does memory work?

**A:** Agent automatically loads:
1. SOUL.md (personality)
2. users/{username}.md (user preferences)
3. Search results (top 3 relevant chunks)
4. Recent conversation (last 5 messages)

See [Memory System](README_MEMORY.md) for details.

### Q: How do I schedule recurring tasks?

**A:** Use TaskScheduler. See [Scheduled Tasks](SCHEDULED_TASKS.md).

```python
task = ScheduledTask("morning", "Daily brief", schedule="08:00")
scheduler.add_task(task)
scheduler.start()
```

### Q: Can I use skills from messaging platforms?

**A:** Yes! See [Skills Integration](SKILLS_INTEGRATION.md).

From Slack: `@bot /code-review src/agent.py`

### Q: Which LLM providers are supported?

**A:** Currently:
- Claude (Anthropic) - Primary
- GLM (z.ai) - Alternative

Model switching: `agent.switch_model("glm")`

## File Organization

```
docs/
├── README.md                          # This file - navigation hub
├── QUICKSTART.md                      # Start here (30 seconds)
├── PULSE_BRAIN.md                     # Monitoring guide (includes Quick Start & comparison)
├── README_ADAPTERS.md                 # Multi-platform adapters
├── README_MEMORY.md                   # Memory system
├── SKILLS_INTEGRATION.md              # Skills from messaging
├── SCHEDULED_TASKS.md                 # Task scheduling
├── CONTROL_AND_CONFIGURATION.md       # Configuration guide
├── WINDOWS_DEPLOYMENT.md              # Windows-specific setup
└── SECURITY_AUDIT_SUMMARY.md          # Security audit report
```

## Getting Help

If you can't find what you're looking for:

1. Check the [main README](../README.md) for overview
2. Run the examples in the project root
3. Review test files (`test_*.py`)
4. Open an issue on GitHub

## Contributing to Documentation

When adding new documentation:

1. Add entry to this index
2. Update relevant learning paths
3. Add to common questions if applicable
4. Follow existing document structure
5. Include code examples
6. Add to appropriate section

---

**Happy building!** Start with the [Quick Start Guide](QUICKSTART.md) and explore from there.