Documentation cleanup and consolidation

Removed redundant/outdated files: - docs/HEARTBEAT_HOOKS.md (legacy, disabled by default) - docs/QUICK_START_PULSE.md (merged into PULSE_BRAIN.md) - docs/MONITORING_COMPARISON.md (merged into PULSE_BRAIN.md) Consolidated monitoring docs: - Merged 3 monitoring files into comprehensive PULSE_BRAIN.md - Added Quick Start section to PULSE_BRAIN.md - Added "Why Pulse & Brain?" comparison section - Added deprecation notices for Heartbeat system Updated README.md: - Clarified Haiku is default model (12x cheaper) - Added prompt caching info (90% savings on Sonnet) - Removed duplicate setup instructions - Linked to SETUP.md for detailed instructions - Added model switching commands section Simplified WINDOWS_QUICK_REFERENCE.md: - Reduced from 224 lines to ~160 lines - Removed redundant development/deployment sections - Kept essential quick commands - Added model switching commands Updated docs/README.md navigation: - Removed references to deleted files - Added deprecation notice for Heartbeat - Updated learning paths - Cleaned up file organization section Result: - Removed 300+ lines of redundant documentation - Consolidated 3 monitoring files into 1 - Improved accuracy and clarity - Easier navigation and maintenance Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-02-13 21:06:15 -07:00
parent a99799bf3d
commit ab3a5afd59
7 changed files with 404 additions and 882 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -9,16 +9,15 @@ Complete documentation for Ajarbot - a lightweight, cost-effective AI agent fram
 | Document | Description | Time to Read |
 |----------|-------------|--------------|
 | [Quick Start Guide](QUICKSTART.md) | 30-second setup and basic agent usage | 5 min |
-| [Pulse & Brain Quick Start](QUICK_START_PULSE.md) | Set up efficient monitoring in minutes | 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) | Production monitoring, homelab |
+| [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 |
-| [Heartbeat Hooks](HEARTBEAT_HOOKS.md) | Proactive health monitoring | System health checks |

 ### Platform Integration

@@ -27,12 +26,16 @@ Complete documentation for Ajarbot - a lightweight, cost-effective AI agent fram
 | [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 |

-### Advanced Topics
+### Configuration

 | Document | Description | Best For |
 |----------|-------------|----------|
 | [Control & Configuration](CONTROL_AND_CONFIGURATION.md) | Configuration management | Customizing behavior |
-| [Monitoring Comparison](MONITORING_COMPARISON.md) | Choosing monitoring approaches | Optimizing costs |
+| [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

@@ -66,21 +69,20 @@ For running bots on Slack, Telegram, or both:
 - User mapping across platforms
 - Custom preprocessors/postprocessors

-### Path 3: Production Monitoring (30 minutes)
+### Path 3: Production Monitoring (20 minutes)

 For cost-effective production deployments:

-1. Read [Pulse & Brain Quick Start](QUICK_START_PULSE.md)
-2. Read [Pulse & Brain Architecture](PULSE_BRAIN.md)
-3. Run `example_bot_with_pulse_brain.py`
-4. Create custom pulse checks
-5. Read [Monitoring Comparison](MONITORING_COMPARISON.md)
+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)
+- Cost optimization (92% savings vs traditional monitoring)

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

@@ -112,13 +114,15 @@ For full-featured production bots:

 ### 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.
+**Key takeaway:** Run proactive monitoring at 1/10th the cost with Quick Start included.

 ### README_ADAPTERS.md
 Multi-platform adapter system:
@@ -151,16 +155,6 @@ Cron-like task scheduling:

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

-### HEARTBEAT_HOOKS.md
-Proactive health monitoring:
- Heartbeat system overview
- Built-in checks (memory, disk, logs)
- Custom health checks
- Alert conditions
- Integration with adapters
-
-**Key takeaway:** Traditional monitoring approach (consider Pulse & Brain for better cost efficiency).
-
 ### README_MEMORY.md
 SQLite-based memory system:
 - Memory architecture
@@ -182,15 +176,6 @@ Configuration management:

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

-### MONITORING_COMPARISON.md
-Choosing the right monitoring:
- Heartbeat vs Pulse & Brain
- Cost comparison
- Use case recommendations
- Migration guide
-
-**Key takeaway:** Decision matrix for monitoring approaches.
-
 ## Common Questions

 ### Q: Which monitoring system should I use?
@@ -198,9 +183,9 @@ Choosing the right monitoring:
 **A:** Use **Pulse & Brain** for production. It's 92% cheaper and more flexible.

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

-See [Monitoring Comparison](MONITORING_COMPARISON.md) for details.
+See [PULSE_BRAIN.md](PULSE_BRAIN.md) for details including comparison and migration guide.

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

@@ -247,16 +232,15 @@ Model switching: `agent.switch_model("glm")`
 ```
 docs/
 ├── README.md                          # This file - navigation hub
-├── QUICKSTART.md                      # Start here
-├── QUICK_START_PULSE.md               # Pulse & Brain quick start
-├── PULSE_BRAIN.md                     # Detailed Pulse & Brain guide
+├── 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
-├── HEARTBEAT_HOOKS.md                 # Legacy heartbeat
 ├── CONTROL_AND_CONFIGURATION.md       # Configuration guide
-└── MONITORING_COMPARISON.md           # Monitoring approaches
+├── WINDOWS_DEPLOYMENT.md              # Windows-specific setup
+└── SECURITY_AUDIT_SUMMARY.md          # Security audit report
 ```

 ## Getting Help