docs: align all CLAUDE.md files and README with actual codebase state

- Update README stats: 24 CLI commands, 5,460+ tests, 310+ files, 100K+ lines
- Fix injection pattern count: 39 → 41 across all references
- Add 6 missing CLI commands to README reference section
- Update .env.example with complete 25+ API key template organized by priority
- Fix 12 CLAUDE.md files with incorrect filenames and outdated component lists
- Update test count references from ~3,500 to 5,460+
- Add missing directories to src/CLAUDE.md (plugins, e2e, channels)
- Correct cognition/CLAUDE.md: knowledge/ and learning/ dirs are active, not removed

Author: PryceHedrick

.env.example

@@ -2,13 +2,40 @@
 # Copy this file to .env and fill in your values
 # NEVER commit .env to version control
 
-# ─────────────────────────────────────────────────────────
-# LLM Providers (at least one required for AI features)
-# ─────────────────────────────────────────────────────────
+# ═══════════════════════════════════════════════════════════
+# CRITICAL (required for core functionality)
+# ═══════════════════════════════════════════════════════════
 
-# Anthropic (primary) — https://console.anthropic.com/settings/keys
+# Anthropic (primary LLM provider) — https://console.anthropic.com/settings/keys
 # ANTHROPIC_API_KEY=sk-ant-...
 
+# Telegram Bot — https://t.me/BotFather
+# TELEGRAM_BOT_TOKEN=123456:ABC-...
+# TELEGRAM_OWNER_USER_ID=123456789
+# TELEGRAM_ALLOWED_USER_IDS=123456789
+
+# ═══════════════════════════════════════════════════════════
+# HIGH PRIORITY (enables key features)
+# ═══════════════════════════════════════════════════════════
+
+# Notion — https://www.notion.so/my-integrations
+# NOTION_API_KEY=ntn_...
+# NOTION_INBOX_DATABASE_ID=32-char-hex-id
+# NOTION_DAILY_LOG_PARENT_ID=32-char-hex-id
+# NOTION_TASKS_DATABASE_ID=32-char-hex-id
+
+# X/Twitter — https://developer.x.com/en/portal/dashboard
+# X_BEARER_TOKEN=AAAA...
+# X_USER_ID=123456789
+
+# Alpha Vantage (market data) — https://www.alphavantage.co/support/#api-key
+# ALPHA_VANTAGE_API_KEY=...
+
+# ═══════════════════════════════════════════════════════════
+# MEDIUM PRIORITY (enhances capabilities)
+# ═══════════════════════════════════════════════════════════
+
+# Additional LLM Providers
 # OpenAI — https://platform.openai.com/api-keys
 # OPENAI_API_KEY=sk-...
 
@@ -18,29 +45,65 @@
 # xAI (Grok) — https://console.x.ai
 # XAI_API_KEY=xai-...
 
-# ─────────────────────────────────────────────────────────
-# Integrations (Optional)
-# ─────────────────────────────────────────────────────────
+# GitHub — https://github.com/settings/tokens
+# GITHUB_TOKEN=ghp_...
 
-# Telegram Bot — https://t.me/BotFather
-# TELEGRAM_BOT_TOKEN=123456:ABC-...
-# TELEGRAM_OWNER_USER_ID=123456789
-# TELEGRAM_ALLOWED_USER_IDS=123456789
+# Weather — https://openweathermap.org/api
+# WEATHER_API_KEY=...
 
-# Notion — https://www.notion.so/my-integrations
-# NOTION_API_KEY=ntn_...
-# NOTION_INBOX_DATABASE_ID=32-char-hex-id
-# NOTION_DAILY_LOG_PARENT_ID=32-char-hex-id
+# Perplexity — https://www.perplexity.ai/settings/api
+# PERPLEXITY_API_KEY=pplx-...
+
+# CoinGecko (crypto prices) — https://www.coingecko.com/en/api
+# COINGECKO_API_KEY=CG-...
 
 # ElevenLabs TTS — https://elevenlabs.io
 # ELEVENLABS_API_KEY=sk_...
 
-# ─────────────────────────────────────────────────────────
-# Core Settings
-# ─────────────────────────────────────────────────────────
+# ═══════════════════════════════════════════════════════════
+# LOW PRIORITY (optional integrations)
+# ═══════════════════════════════════════════════════════════
+
+# Readwise — https://readwise.io/access_token
+# READWISE_API_KEY=...
+
+# Stripe — https://dashboard.stripe.com/apikeys
+# STRIPE_SECRET_KEY=sk_...
+
+# Toggl — https://track.toggl.com/profile (scroll to API Token)
+# TOGGL_API_TOKEN=...
+# TOGGL_WORKSPACE_ID=...
+
+# Spotify — https://developer.spotify.com/dashboard
+# SPOTIFY_ACCESS_TOKEN=...
+
+# Cal.com — https://app.cal.com/settings/developer/api-keys
+# CALCOM_API_KEY=cal_...
+
+# Product Hunt — https://www.producthunt.com/v2/oauth/applications
+# PRODUCTHUNT_ACCESS_TOKEN=...
+
+# ═══════════════════════════════════════════════════════════
+# NO API KEY NEEDED (work out of the box)
+# ═══════════════════════════════════════════════════════════
+# These integrations work without configuration:
+# - Hacker News (public API)
+# - RSS feeds (public)
+# - Google Trends (scraping)
+# - Ollama (local LLM — install from https://ollama.ai)
+# - Anki (local — requires AnkiConnect plugin)
+# - Apple Calendar/Reminders (macOS AppleScript)
+# - Whisper (local — requires whisper CLI)
+
+# ═══════════════════════════════════════════════════════════
+# CORE SETTINGS
+# ═══════════════════════════════════════════════════════════
 
 # Gateway port (default: 3141)
 # ARI_PORT=3141
 
+# Internal API key for service-to-service auth
+# ARI_API_KEY=...
+
 # Node environment
 # NODE_ENV=development

README.md

@@ -53,7 +53,7 @@ ARI is a **multi-agent AI operating system** that runs entirely on your machine.
 **Core Properties:**
 - **Local-First** — All data stays on your machine. No cloud dependencies.
 - **Auditable** — Every decision is logged in a tamper-evident SHA-256 hash chain.
-- **Secure by Design** — Loopback-only gateway. 39-pattern injection detection. Zero trust architecture.
+- **Secure by Design** — Loopback-only gateway. 41-pattern injection detection. Zero trust architecture.
 - **Autonomous** — Morning/evening briefings, market monitoring, intelligent task management.
 
 > **Note**: This is a framework. The code is open source. Your data is not.
@@ -76,7 +76,7 @@ ARI is a **multi-agent AI operating system** that runs entirely on your machine.
 - Intelligent task prioritization
 
 **Security & Governance**
-- 39 injection patterns across 14 categories
+- 41 injection patterns across 14 categories
 - SHA-256 hash-chained audit trail
 - 15-member constitutional council
 - 6 trust levels with risk multipliers
@@ -93,10 +93,10 @@ ARI is a **multi-agent AI operating system** that runs entirely on your machine.
 - Core Agent (orchestration)
 
 **Developer Experience**
-- 23 CLI commands
-- 4,885+ tests across 189 files
-- 200+ TypeScript files
-- 50,000+ lines of code
+- 24 CLI commands
+- 5,460+ tests across 218 files
+- 310+ TypeScript files
+- 100,000+ lines of code
 - Cognitive layer (LOGOS/ETHOS/PATHOS)
 
 </td>
@@ -162,7 +162,7 @@ graph TB
 | **Agents** | Agent coordination and execution | Guardian (threat detection), Planner (task decomposition), Executor (tool invocation), Memory Manager (provenance tracking), Core (orchestration) |
 | **Strategic** | Governance and quality control | Council (15-member voting), Arbiter (6 constitutional rules), Overseer (5 quality gates) |
 | **Execution** | Process lifecycle | Daemon (macOS launchd integration), Health Monitor, Git Sync |
-| **Interfaces** | User interaction | CLI (23 commands), Dashboard (React), External Integrations |
+| **Interfaces** | User interaction | CLI (24 commands), Dashboard (React), External Integrations |
 
 **Dependency Rule:** Lower layers CANNOT import higher layers. Cross-layer communication via EventBus only.
 
@@ -174,7 +174,7 @@ Every message flows through a **multi-stage security pipeline** before execution
 
 ```mermaid
 flowchart TD
-    Start([Inbound Message]) --> Sanitize[Sanitizer<br/>39 Injection Patterns]
+    Start([Inbound Message]) --> Sanitize[Sanitizer<br/>41 Injection Patterns]
     Sanitize -->|Clean| TrustCheck{Trust Level<br/>Assessment}
     Sanitize -->|Malicious| Block1[BLOCK]
 
@@ -245,7 +245,7 @@ sequenceDiagram
 
     U->>G: POST /message
     G->>S: Sanitize input
-    S->>S: Check 39 patterns
+    S->>S: Check 41 patterns
     alt Malicious
         S-->>G: BLOCK
         G-->>U: 400 Bad Request
@@ -427,6 +427,12 @@ ari audit-report              Generate audit reports
 ari autonomous [start|stop]   Autonomous agent control
 ari cognitive [analyze]       Cognitive layer tools
 ari budget [show|reset]       Budget management
+ari crypto [prices|portfolio] Crypto market data
+ari pokemon [search|value]    Pokemon TCG tools
+ari speak <text>              Text-to-speech
+ari plugin [list|install]     Plugin management
+ari provider [list|set]       AI provider management
+ari diagram [arch|flow]       Architecture diagrams
 ```
 
 ---

src/CLAUDE.md

@@ -9,20 +9,22 @@ This is the main source directory for ARI. Quick navigation:
 | 2. System | `system/` | Routing, storage, context loading |
 | 3. Agents | `agents/` | Multi-agent coordination |
 | 4. Governance | `governance/` | Council, arbiter, overseer, policy engine |
-| 5. Ops | `ops/` | Daemon, infrastructure |
+| 5. Ops | `ops/` | Daemon, health monitor, git sync |
 | 6. CLI | `cli/` | User interface commands (24 commands) |
 
 Additional directories:
-- `ai/` — AIOrchestrator, model registry, value scorer, prompt builder
-- `autonomous/` — Proactive agent, scheduler, briefings
-- `execution/` — Tool registry and executor
-- `integrations/` — External services (Notion, SMS, Cowork)
+- `ai/` — AIOrchestrator, model registry (20 models), value scorer, batch processor
+- `autonomous/` — Proactive agent, scheduler (35 tasks), briefings, market monitor
+- `execution/` — Tool registry, tool executor, model router
+- `integrations/` — 21 external services (Notion, Telegram, Apple, GitHub, RSS, Weather, etc.)
+- `plugins/` — Content engine, crypto, Pokemon TCG, Telegram bot, TTS
 - `mcp/` — Model Context Protocol server
 - `prompts/` — Prompt building utilities
-- `observability/` — Metrics, alerts, execution history
-- `api/` — REST routes (modular) and WebSocket server
-- `channels/` — Communication channels (Telegram, Slack, Webhook, etc.)
-- `skills/` — Skill definitions
+- `observability/` — Metrics, alerts, cost tracking, execution history
+- `api/` — REST routes (16 route files) and WebSocket server
+- `channels/` — Communication channel abstraction (registry, router, bridge)
+- `skills/` — Skill definitions (diagram generator)
+- `e2e/` — End-to-end test runner and setup
 
 ## Quick Rules
 
@@ -35,7 +37,7 @@ Additional directories:
 
 - `kernel/types.ts` — All Zod schemas
 - `kernel/event-bus.ts` — Typed pub/sub
-- `kernel/sanitizer.ts` — Injection detection
+- `kernel/sanitizer.ts` — 41-pattern injection detection
 - `agents/core.ts` — Message pipeline
 - `ai/orchestrator.ts` — AI model routing and orchestration
 

src/ai/CLAUDE.md

@@ -24,14 +24,21 @@ AIOrchestrator.execute(request)
 
 | File | Purpose |
 |------|---------|
+| orchestrator.ts | THE single entry point |
 | types.ts | All Zod schemas (ADR-006) |
-| model-registry.ts | Single source of truth for models + pricing |
+| model-registry.ts | Single source of truth for 20 models + pricing |
 | value-scorer.ts | ValueScore algorithm + task classification |
 | circuit-breaker.ts | Three-state failure protection |
 | response-evaluator.ts | Post-response quality assessment |
 | prompt-assembler.ts | Prompt construction with cache_control |
 | ai-policy-governor.ts | Council governance bridge |
-| orchestrator.ts | THE single entry point |
+| provider-registry.ts | Multi-provider management (Anthropic, OpenAI, Google, xAI) |
+| cascade-router.ts | Cascade model routing |
+| request-classifier.ts | Request classification and routing |
+| embedding-service.ts | Text embedding generation |
+| performance-tracker.ts | Model performance tracking |
+| batch-processor.ts | Batch API processing |
+| index.ts | Module exports |
 
 ## Layer Rules
 

src/api/CLAUDE.md

@@ -6,7 +6,7 @@ REST API and WebSocket endpoints for ARI operations.
 
 | Component | Purpose |
 |-----------|---------|
-| routes/ | Modular Fastify route plugins |
+| routes/ | Modular Fastify route plugins (15 route files) |
 | ws.ts | WebSocket event broadcaster |
 | index.ts | API initialization and exports |
 
@@ -20,6 +20,14 @@ Routes are split into modular files under `routes/`:
 - `audit.ts` — `/api/audit/*`
 - `budget.ts` — `/api/budget/*`
 - `autonomous.ts` — `/api/autonomous/*`
+- `alerts.ts` — `/api/alerts/*`
+- `analytics.ts` — `/api/analytics/*`
+- `approval-queue.ts` — `/api/approval-queue/*`
+- `dashboard.ts` — `/api/dashboard/*`
+- `metrics.ts` — `/api/metrics/*`
+- `scheduler.ts` — `/api/scheduler/*`
+- `subagents.ts` — `/api/subagents/*`
+- `shared.ts` — Shared `ApiDependencies` type
 
 ## Endpoints
 

src/channels/CLAUDE.md

@@ -6,10 +6,11 @@ Abstraction layer for multi-channel communication.
 
 | Component | Purpose |
 |-----------|---------|
-| base.ts | Base channel interface |
-| telegram.ts | Telegram channel adapter |
-| email.ts | Email communication channel |
-| discord.ts | Discord integration |
+| types.ts | Channel interface definitions |
+| registry.ts | Channel registry and lookup |
+| router.ts | Message routing across channels |
+| message-bridge.ts | Bridge between EventBus and channels |
+| index.ts | Module exports |
 
 ## Channel Interface
 

src/cognition/CLAUDE.md

@@ -18,11 +18,9 @@ Layer 0: Cognitive (trimmed to essentials)
 └── index.ts    — Barrel exports
 ```
 
-**Removed modules** (Phase 2 simplification):
-- `knowledge/` — 92 curated sources (not connected to core pipeline)
-- `learning/` — 27-file educational platform (kept only decision-journal.ts)
-- `ux/` — 12-file visualization system
-- `visualization/` — Insight formatters
+**Additional modules** (active):
+- `knowledge/` — Cognitive source management (5 files: cognitive-sources, content-validator, source-manager, specializations, index)
+- `learning/` — Self-improvement subsystem (7 files: decision-journal, calibration-tracker, gap-analysis, learning-loop, performance-review, self-assessment, index)
 
 ## Three Pillars
 

src/execution/CLAUDE.md

@@ -7,8 +7,10 @@ Tool registry and executor for ARI's capability invocation.
 | Component | Purpose |
 |-----------|---------|
 | tool-registry.ts | Register and manage available tools |
-| executor.ts | Execute tools with permission checks |
+| tool-executor.ts | Execute tools with permission checks |
+| model-router.ts | Route requests to appropriate AI models |
 | types.ts | Tool and execution type definitions |
+| index.ts | Module exports |
 
 ## Tool Categories
 

src/integrations/CLAUDE.md

@@ -1,14 +1,32 @@
 # Integrations Layer
 
-External service integrations for ARI.
+External service integrations for ARI. 21 integration directories.
 
 ## Components
 
-| Integration | Purpose | Files |
-|-------------|---------|-------|
-| Notion | Task and document management | notion/ |
-| SMS | Mobile notifications | sms/ |
-| Cowork | Claude Cowork plugins | cowork/ |
+| Integration | Purpose | API Key Required |
+|-------------|---------|-----------------|
+| anki/ | Spaced repetition flashcards | No (local) |
+| apple/ | Calendar, Reminders, Focus Mode | No (AppleScript) |
+| calcom/ | Scheduling and bookings | Yes |
+| cowork/ | Claude Cowork plugin generation | No |
+| github/ | Repository and PR monitoring | Yes |
+| hackernews/ | Tech news aggregation | No |
+| notion/ | Task and document management | Yes |
+| ollama/ | Local LLM inference | No (local) |
+| perplexity/ | AI-powered research | Yes |
+| producthunt/ | Product launch tracking | Yes |
+| readwise/ | Reading highlights sync | Yes |
+| rss/ | RSS feed aggregation | No |
+| sms/ | Mobile notifications | Yes |
+| spotify/ | Music and podcast tracking | Yes |
+| stripe/ | Payment and revenue monitoring | Yes |
+| telegram/ | Bot and messaging | Yes |
+| toggl/ | Time tracking | Yes |
+| trends/ | Google Trends monitoring | No |
+| twitter/ | Social media monitoring | Yes |
+| weather/ | Weather forecasts | Yes |
+| whisper/ | Speech-to-text transcription | No (local) |
 
 ## Notion Integration
 
@@ -19,28 +37,6 @@ const notion = new NotionClient(process.env.NOTION_API_KEY);
 await notion.createPage({ title: 'ARI Task', content: '...' });
 ```
 
-## SMS Integration
-
-```typescript
-import { SMSConversation } from './integrations/sms';
-
-const sms = new SMSConversation(config);
-await sms.start();
-sms.on('command', (cmd) => handleCommand(cmd));
-```
-
-## Cowork Plugin System
-
-Generate Claude Cowork compatible plugins:
-```typescript
-import { generatePlugin } from './integrations/cowork';
-
-await generatePlugin({
-  name: 'ari-tasks',
-  tools: ['create_task', 'list_tasks'],
-});
-```
-
 ## Security
 
 - API keys stored in environment variables