From 8eb891bc6ef3dc25dda36d7bca0d7f1b71ce1a5d Mon Sep 17 00:00:00 2001
From: Commander <danny@gositeme.com>
Date: Tue, 7 Apr 2026 16:58:45 -0400
Subject: [PATCH] README: enhanced with line counts, design decisions, full
 source file table

---
 README.md | 41 ++++++++++++++++++++++++++---------------
 1 file changed, 26 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 9660e32..ecf1938 100644
--- a/README.md
+++ b/README.md
@@ -1,25 +1,29 @@
 # Alfred Agent
 
-The autonomous AI agent runtime for Alfred Linux and Alfred IDE.
+**Autonomous AI agent runtime — 1,870 lines, 8 source files, 14 tools, multi-provider.**
+
+The standalone agent that powers AI capabilities across Alfred Linux and Alfred IDE. Handles tool-calling loops, multi-provider LLM routing, session persistence, and a 7-section system prompt. Runs as a PM2 service or interactive CLI.
 
 ## Architecture
 
-- **Multi-provider support**: Anthropic Claude, OpenAI GPT, Groq (via OpenAI-compatible adapter)
-- **14 built-in tools**: File operations, web search, shell execution, code analysis
-- **Session persistence**: Full conversation history stored to disk
-- **7-section system prompt**: Structured reasoning with identity, capabilities, safety guardrails
+- **Multi-provider**: Anthropic Claude, OpenAI GPT, Groq (via OpenAI-compatible adapter)
+- **14 built-in tools**: File I/O, web search, shell execution, code analysis, workflow hooks
+- **Session persistence**: Full conversation history stored to disk as JSON
+- **7-section system prompt**: Identity, capabilities, tool descriptions, safety guardrails, context, reasoning, output formatting
+- **Core loop**: Autonomous tool-calling with reasoning → action → observation cycle
 
-## Source Files
+## Source Files (1,870 lines total)
 
-| File | Purpose |
-|------|---------|
-| `src/providers.js` | Multi-LLM provider abstraction (Anthropic, OpenAI, Groq) |
-| `src/tools.js` | 14 tool definitions — file I/O, search, shell, analysis |
-| `src/prompt.js` | 7-section system prompt builder |
-| `src/session.js` | Conversation session manager with disk persistence |
-| `src/agent.js` | Core agent loop — tool calling, reasoning, response synthesis |
-| `src/cli.js` | Interactive CLI interface |
-| `src/index.js` | HTTP server (port 3102) with health check and message endpoints |
+| File | Lines | Purpose |
+|------|-------|---------|
+| `src/tools.js` | 542 | 14 tool definitions — file read/write, search, shell exec, code analysis |
+| `src/hooks.js` | 334 | Lifecycle hooks — pre/post tool execution, response filtering |
+| `src/cli.js` | 205 | Interactive CLI with streaming output |
+| `src/agent.js` | 196 | Core agent loop — tool calling, reasoning, response synthesis |
+| `src/prompt.js` | 174 | 7-section system prompt builder |
+| `src/index.js` | 156 | HTTP server (port 3102), health check, message endpoints |
+| `src/session.js` | 141 | Session manager with disk persistence |
+| `src/providers.js` | 122 | LLM provider abstraction (Anthropic, OpenAI, Groq adapters) |
 
 ## Running
 
@@ -32,6 +36,13 @@ pm2 start src/index.js --name alfred-agent
 # Health: curl http://127.0.0.1:3102/health
 ```
 
+## Design Decisions
+
+- **No framework**: Pure Node.js, no Express, no LangChain, no abstractions-for-abstractions
+- **Provider-agnostic**: Same agent loop works with any OpenAI-compatible API
+- **Stateful sessions**: Every conversation persists to `data/sessions/` — no lost context
+- **Tool-first**: Agent reasons about WHAT to do, tools handle HOW
+
 ## License
 
 AGPL-3.0 — GoSiteMe Inc.