docs: comprehensive AGENTS.md audit and corrections#732
Merged
Conversation
Major fixes: - Default model: claude-sonnet-4.6 → claude-opus-4.6 - max_iterations default: 60 → 90 (also fixed in config.py OPTIONAL_ENV_VARS description) - chat() signature: chat(user_message, task_id) → chat(message) - Agent loop: _run_agent_loop() doesn't exist, loop is in run_conversation() - Removed async/await references (agent is entirely synchronous) - KawaiiSpinner location: run_agent.py → agent/display.py - NOUS_API_KEY removed (not used by any tool), replaced with VOICE_TOOLS_OPENAI_KEY - OPENAI_API_KEY for Whisper → VOICE_TOOLS_OPENAI_KEY - check_for_missing_config() → check_config_version() + get_missing_env_vars() - Adding tools: '2 files' → '3 files' (tool + model_tools.py + toolsets.py) - Venv path: venv/ → .venv/ - Trajectory output path: trajectories/*.jsonl → trajectory_samples.jsonl - process_command() location clarified (HermesCLI in cli.py, not commands.py) - REQUIRED_ENV_VARS noted as intentionally empty - _config_version noted as currently at version 5 New content: - Project structure: added 40+ missing files across agent/, hermes_cli/, tools/, gateway/ - Full gateway/ directory listing with all modules and platforms/ - Added honcho_integration/, scripts/, tests/ directories - Added hermes_constants.py, hermes_time.py, trajectory_compressor.py, utils.py - CLI commands table: added 25+ missing commands (model, login, logout, whatsapp, skills subsystem, tools, insights, gateway start/stop/restart/status/uninstall, sessions export/delete/prune/stats, config path/env-path/show) - Gateway slash commands section with all 20+ commands - Platform toolsets: added hermes-cli, hermes-slack, hermes-homeassistant, hermes-gateway - Gateway: added Home Assistant as supported platform
NOUS_API_KEY is unused — vision tools use OPENROUTER_API_KEY or Nous Portal OAuth (auth.json), and MoA tools use OPENROUTER_API_KEY. Removed from: - hermes_cli/config.py: api_keys allowlist for config set routing - .env.example: example env file entry and comment - tests/hermes_cli/test_set_config_value.py: parametrize test data - tests/integration/test_web_tools.py: updated comments and log messages to reference 'auxiliary LLM provider' instead of NOUS_API_KEY No HECATE references found in codebase (already cleaned up).
New documentation pages (1,823 lines): - getting-started/learning-path.md: 3-tier learning path table (beginner/intermediate/advanced) + use-case-based navigation - guides/tips.md: Tips & Best Practices quick-wins collection covering prompting, CLI power user tips, context files, memory, performance/cost, messaging, and security - guides/daily-briefing-bot.md: End-to-end tutorial building an automated daily news briefing with cron + web search + messaging - guides/team-telegram-assistant.md: Full walkthrough setting up a team Telegram bot with BotFather, gateway, DM pairing, and production deployment - guides/python-library.md: Guide to using AIAgent as a Python library — basic usage, multi-turn conversations, toolset config, trajectories, custom prompts, and integration examples (FastAPI, Discord bot, CI/CD) - reference/faq.md: Centralized FAQ (8 questions) + troubleshooting guide (6 categories, 18 specific issues) with problem/cause/solution format Sidebar restructure: - Added 'Guides & Tutorials' as new top-level section - Reorganized flat Features list (17 items) into 5 subcategories: Core Features, Automation, Web & Media, Integrations, Advanced - Added FAQ to Reference section - Updated index.md quick links table Docusaurus build verified clean.
All four platform guides rewritten from thin ~60-line summaries to comprehensive step-by-step setup guides with current (2025-2026) info: telegram.md (74 → 196 lines): - Full BotFather walkthrough with customization commands - Privacy mode section with critical group chat gotcha - Multiple user ID discovery methods - Voice message setup (Whisper STT + TTS bubbles + ffmpeg) - Group chat usage patterns and admin mode - Recent Bot API features (privacy policy requirement, streaming) - Troubleshooting table (6 issues) discord.md (57 → 260 lines): - Complete Developer Portal walkthrough (application, bot, intents) - Detailed Privileged Gateway Intents section with warning about Message Content Intent being #1 failure cause - Invite URL generation via Installation tab (new 2024) and manual - Permission integer calculation (274878286912 recommended) - Developer Mode user ID discovery - Bot behavior documentation (DMs, channels, no-prefix) - Troubleshooting table (6 issues) slack.md (57 → 214 lines): - Warning about classic Slack apps deprecated since March 2025 - Full scope tables (required + optional) with purposes - Socket Mode setup with App-Level Token (xapp-) - Event Subscriptions configuration - User ID discovery via profile - Two-token architecture explained (xoxb- + xapp-) - Troubleshooting table whatsapp.md (77 → 193 lines): - Clarified whatsapp-web.js (not Business API) with ban risk warnings - Linux Chromium dependencies (Debian + Fedora) - Setup wizard QR code scanning workflow - Session persistence with LocalAuth - Second phone number options with cost table - WhatsApp Web protocol update warnings - Troubleshooting table (7 issues) Docusaurus build verified clean.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Comprehensive documentation audit, restructure, and expansion across 4 commits.
Commit 1: AGENTS.md Audit & Corrections
Fixed 15+ factual errors in AGENTS.md and added significant missing documentation:
claude-sonnet-4.6claude-opus-4.6max_iterations: int = 60max_iterations: int = 90chat(user_message, task_id)chat(message)→run_conversation()has task_id_run_agent_loop()run_conversation()await execute_tool()(async)run_agent.pyagent/display.pyNOUS_API_KEYfor vision/MoA toolsOPENAI_API_KEYfor WhisperVOICE_TOOLS_OPENAI_KEYcheck_for_missing_config()check_config_version()+get_missing_env_vars()source venv/bin/activate.venvAdded 40+ missing files to project structure, 25+ missing CLI commands, gateway slash commands section, missing platform toolsets.
Commit 2: Remove NOUS_API_KEY References
Removed all references from: config.py, .env.example, tests (4 files total). Also fixed config.py HERMES_MAX_ITERATIONS description (said 60, actual default is 90).
Commit 3: Guides & Tutorials Section + Sidebar Restructure
6 new documentation pages (1,823 lines):
getting-started/learning-path.md— 3-tier learning path table + use-case navigationguides/tips.md— Tips & Best Practices quick-wins collection (7 categories)guides/daily-briefing-bot.md— Tutorial: automated daily news briefing with cronguides/team-telegram-assistant.md— Tutorial: team Telegram bot with DM pairingguides/python-library.md— Using AIAgent as a Python library (FastAPI, Discord, CI/CD examples)reference/faq.md— FAQ (8 questions) + troubleshooting (6 categories, 18 issues)Sidebar restructure:
Guides & Tutorialstop-level sectionCommit 4: Comprehensive Platform Setup Guides Rewrite
All 4 messaging platform guides rewritten from ~60-line summaries to comprehensive step-by-step guides with current 2025-2026 information:
Test Results
All 2,343 tests pass. Docusaurus build verified clean.