docs: comprehensive update to CLAUDE.md with current architecture

- Complete rewrite reflecting current codebase architecture and features
- Document streaming response processing and thread management
- Add Docker architecture details and environment variables
- Include security features, deployment options, and performance characteristics
- Document thread title filtering and session management flow
- Add troubleshooting section and automated publishing details

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: Stewart86

CLAUDE.md

@@ -1,74 +1,166 @@
-# Bobby Memory Index
+# Bobby - Discord AI Assistant Bot
 
-This file maintains references to Bobby's memory documents stored in the docs/ directory.
+## Overview
 
-## Memory Access Instructions
+Bobby is a Discord chatbot that helps answer questions about your codebase, file bugs, and translate business requirements into technical requirements. Bobby leverages Claude Code to understand your codebase and provide intelligent responses in a self-hosted, privacy-first environment.
 
-- Read documents from the docs/ directory to retrieve stored information
-- Store new information in topic-specific markdown files in the docs/ directory
-- Update this index when creating new documents
+## Core Architecture
 
-## Memory Index
+### Main Components
 
-- No memories stored yet
+- **index.js** - Main Node.js application using Bun runtime
+- **Discord.js** - Handles Discord bot interactions and thread management  
+- **Claude Code CLI** - Powers AI analysis of codebases with streaming responses
+- **GitHub CLI** - Creates issues automatically when bugs are detected
+- **Docker Container** - Self-contained environment with all dependencies
 
-## Bobby Commands
+### Environment Variables Required
 
-The following commands can be used to interact with Bobby:
+```
+DISCORD_TOKEN=your_discord_bot_token
+ANTHROPIC_API_KEY=your_anthropic_api_key  
+GH_TOKEN=your_github_personal_access_token
+GITHUB_REPO=owner/repo-name
+ALLOWED_DISCORD_SERVERS=server_id1,server_id2 (optional)
+```
 
-- `Hey Bobby, [your question]` - Ask Bobby a question about the codebase (creates a new thread)
-- `Bobby, what does [code or function] do?` - Ask Bobby to explain specific code (creates a new thread)
-- `Bobby, is there a bug in [feature or component]?` - Ask Bobby to check for bugs (creates a new thread)
+### Docker Architecture
+
+- **Base Image**: `oven/bun:latest`
+- **Dependencies**: Git, GitHub CLI v2.61.0, Claude Code CLI
+- **Working Directory**: `/app`
+- **Repository Clone**: `/app/repo` (target repository)
+- **Data Storage**: `/app/data` (Claude Code sessions and configs)
+- **Entrypoint**: `entrypoint.sh` (handles authentication and setup)
 
 ## Thread-Based Session Management
 
-Bobby now uses Discord threads for session management:
+Bobby uses Discord threads for session management with streaming responses:
 
 1. **New Conversations**: Mention Bobby in any channel to create a new thread with a new Claude Code session
 2. **Follow-ups**: Simply type in the thread (no need to mention Bobby) to continue the same Claude Code session
 3. **Thread Naming**: Threads are automatically named as `Bobby - Title - session-id` where:
-   - `Title` is a 3-5 word summary generated by Claude
+   - `Title` is a 3-5 word summary generated by Claude (hidden from user via regex)
    - `session-id` is the Claude Code session identifier
+4. **Streaming Responses**: Real-time message streaming with JSON parsing
+5. **Auto-Archive**: Threads automatically archive after 24 hours of inactivity
 
-### How It Works
+### Session Flow
 
-- Each thread maintains its own Claude Code session context
-- All messages in a thread share the same session (memory retained)
-- Starting a new conversation creates a new thread and new session
-- No cleanup needed - threads auto-archive after 24 hours of inactivity
+```
+User mentions Bobby → Create thread → Spawn Claude process → Stream JSON responses → Extract session ID → Update thread name
+```
 
-## Available Tools
+## Available Tools & Capabilities
 
-Bobby has access to the following tools:
+Bobby has access to the following tools through Claude Code:
 
-- Claude Code - For codebase analysis and question answering (READ-ONLY)
-- GitHub CLI - For issue creation and repository access
-- Discord.js - For interaction with Discord
+- **Read, Grep, Glob, LS** - File operations for codebase analysis
+- **Bash(gh:*)** - GitHub CLI for issue creation and repository access  
+- **Bash(git:*)** - Git commands for repository operations
+- **WebFetch, WebSearch** - Web access for additional information
 
 ## Important Limitations
 
 Bobby is designed as a **READ-ONLY** assistant:
 
 - ✅ Can analyze, explore, and read your codebase
-- ✅ Can create GitHub issues for bugs and improvements
+- ✅ Can create GitHub issues for bugs and improvements  
 - ✅ Can provide code recommendations and suggestions
+- ✅ Can fetch latest git changes and analyze repository state
 - ❌ Cannot modify, edit, or write code files
 - ❌ Cannot make commits or push changes
 
-If you ask Bobby to modify code, he will politely decline and offer to create a GitHub issue instead.
+**Enforcement**: The system prompt explicitly instructs Claude to immediately decline any modification requests and offer to create GitHub issues instead.
+
+## System Prompt Configuration
+
+Bobby uses an optimized system prompt with:
+
+- **Role Definition**: Expert code analysis assistant
+- **Context Awareness**: Discord environment constraints
+- **Session Management**: Thread-based conversation handling
+- **Response Format**: Concise, actionable responses with bullet points
+- **Thread Title Generation**: `[THREAD_TITLE: <title>]` pattern (filtered from user view)
+- **GitHub Integration**: Automatic issue creation for bugs and feature requests
+
+## Streaming Response Processing
+
+Bobby implements real-time response streaming:
+
+1. **Process Spawning**: `claude` CLI with `--output-format stream-json`
+2. **JSON Parsing**: Line-by-line JSON object parsing from stdout
+3. **Content Filtering**: Removes `[THREAD_TITLE: <title>]` patterns before sending to user
+4. **Session Tracking**: Extracts session IDs and thread titles from metadata
+5. **Error Handling**: Captures stderr and provides fallback responses
+
+## Security Features
+
+- **Server Whitelist**: `ALLOWED_DISCORD_SERVERS` environment variable controls access
+- **Private Bot**: Designed to be run as private Discord application
+- **Token Validation**: Validates all required environment variables on startup
+- **Container Isolation**: Runs in isolated Docker environment
+- **Data Persistence**: Claude Code sessions persist in `/app/data` volume
+
+## Deployment Options
+
+### Docker Hub (Recommended)
+```bash
+docker run -d --name bobby \
+  -e DISCORD_TOKEN=your_token \
+  -e ANTHROPIC_API_KEY=your_key \
+  -e GH_TOKEN=your_gh_token \
+  -e GITHUB_REPO=owner/repo \
+  -v bobby-data:/app/data \
+  stewart86/bobby:latest
+```
+
+### Build from Source
+```bash
+git clone https://github.com/Stewart86/bobby.git
+docker build -t bobby-bot .
+docker run -d --name bobby [env vars] bobby-bot
+```
+
+## Automated Publishing
+
+GitHub Actions workflow (`docker-publish.yml`) automatically:
+- Builds Docker images on commits to main
+- Creates versioned releases on git tags
+- Publishes to Docker Hub as `stewart86/bobby`
+- Syncs README to Docker Hub (with error tolerance)
+
+## Issue Filing Guidelines
+
+When Bobby detects bugs, it follows these guidelines:
+
+1. **Clear title** describing the bug
+2. **Detailed description** with technical details
+3. **Reproduction steps** when available  
+4. **Labels**: "bug,bobby-detected" or "enhancement,bobby-detected"
+5. **Attribution**: "Detected by Bobby (Claude Code assistant)"
+6. **Response Format**: Always includes issue link and number
+
+## Memory Management
+
+Bobby stores information in Markdown files in the `docs/` directory, organized by topic. The `CLAUDE.md` file serves as an index to these memory files, helping Claude find relevant information during conversations.
+
+## Troubleshooting
+
+### Claude API Authentication Issues
 
-## Guidelines for Issue Filing
+If authentication errors occur (known issue):
 
-When Bobby detects a bug, it follows these guidelines for filing issues:
+1. Access running container: `docker exec -it bobby /bin/sh`
+2. Manually authenticate: `claude` (follow prompts)
+3. Exit container: `exit`
 
-1. Clear title describing the bug
-2. Detailed description of the issue
-3. Steps to reproduce (when available)
-4. Tagged with "bobby-detected" label
+This typically resolves authentication problems in the Docker environment.
 
-## Memory Locations
+## Performance Characteristics
 
-- General queries: docs/general-queries.md
-- Bugs: docs/bugs.md
-- Technical requirements: docs/technical-requirements.md
-- Feature requests: docs/feature-requests.md
+- **Startup Time**: ~30 seconds (includes repository cloning)
+- **Response Time**: Real-time streaming (starts within 2-3 seconds)
+- **Memory Usage**: ~100-200MB base + Claude Code processes
+- **Storage**: Minimal (repository clone + session data)
+- **Network**: Outbound only (Discord, GitHub, Anthropic APIs)