From b2d85ac4aefd1e9b9435fbb8ec97faf08e4248b6 Mon Sep 17 00:00:00 2001
From: Amr Gharbeia <amr@gharbeia.net>
Date: Wed, 22 Apr 2026 16:02:24 -0400
Subject: [PATCH] refactor: Reorganize .env.example into logical sections

- Group variables by purpose (Identity, LLM, Daemon, Security, etc.)
- Remove unused variables (LLM_API_KEY, LLM_ENDPOINT, GTD_ENFORCE_INTEGRITY, ORG_AGENT_WEB_PORT, RECIPIENT_ID)
- Add section headers for clarity
---
 .env.example | 88 +++++++++++++++++++++++++++++-----------------------
 1 file changed, 49 insertions(+), 39 deletions(-)

diff --git a/.env.example b/.env.example
index 0ea905d..c5e861c 100644
--- a/.env.example
+++ b/.env.example
@@ -1,50 +1,72 @@
-# opencortex: Neural Engine Configuration
-# Core LLM Providers
-LLAMACPP_ENDPOINT="http://localhost:8080"
-GEMINI_API_KEY="your_gemini_key_here"
-ANTHROPIC_API_KEY="your_anthropic_key_here"
-OPENAI_API_KEY="your_openai_key_here"
-GROQ_API_KEY="your_groq_key_here"
+# opencortex: Environment Configuration Template
+# Copy this to .env and fill in your values
+
+# =============================================================================
+# IDENTITY
+# =============================================================================
+MEMEX_USER="YourName"
+MEMEX_ASSISTANT="AgentName"
+
+# =============================================================================
+# LLM PROVIDERS (OpenRouter recommended as primary)
+# =============================================================================
 OPENROUTER_API_KEY="your_openrouter_key_here"
+OPENAI_API_KEY="your_openai_key_here"
+ANTHROPIC_API_KEY="your_anthropic_key_here"
+GROQ_API_KEY="your_groq_api_key_here"
+GEMINI_API_KEY="your_gemini_key_here"
 
-# Legacy/Default (Optional)
-LLM_API_KEY="your_api_key_here"
-LLM_ENDPOINT="https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent"
+# Cascade order (first available provider wins)
+PROVIDER_CASCADE="openrouter,openai,anthropic,groq,gemini-api,ollama"
 
-# Communication Gateways
+# =============================================================================
+# LOCAL LLM (Ollama - runs offline)
+# =============================================================================
+OLLAMA_HOST="localhost:11434"
+
+# llama.cpp backend (for local GGUF models)
+LLAMACPP_ENDPOINT="http://localhost:8080"
+
+# =============================================================================
+# MESSAGING GATEWAYS (optional)
+# =============================================================================
 TELEGRAM_BOT_TOKEN="your_telegram_bot_token_here"
 SIGNAL_ACCOUNT_NUMBER="+1..."
 
-# System 2: Symbolic Constraints
-SAFETY_BLOCK_SHELL=true
-GTD_ENFORCE_INTEGRITY=true
-
-# Harness Protocol Daemon Configuration
+# =============================================================================
+# DAEMON CONFIGURATION
+# =============================================================================
 ORG_AGENT_DAEMON_PORT=9105
-ORG_AGENT_WEB_PORT=8080
 DAEMON_HOST="0.0.0.0"
 HEARTBEAT_INTERVAL=60
 DAEMON_SLEEP_INTERVAL=3600
-
-# Outbound Communication Defaults
 DEFAULT_ACTUATOR="cli"
 SILENT_ACTUATORS="cli,system-message,emacs"
 
-# Core Skill Requirements
-# A comma-separated list of skill Org files (without extension) required for boot.
+# =============================================================================
+# SECURITY
+# =============================================================================
+SAFETY_BLOCK_SHELL=true
+PROTOCOL_ENFORCE_HMAC=false
+PROTOCOL_HMAC_SECRET="change-this-to-a-secure-random-string"
+
+# =============================================================================
+# BOOTSTRAP
+# =============================================================================
 MANDATORY_SKILLS="org-skill-policy,org-skill-bouncer"
 
-# Context Management & Peripheral Vision
+# =============================================================================
+# CONTEXT / MEMORY
+# =============================================================================
 CONTEXT_SEMANTIC_THRESHOLD=0.75
 CONTEXT_LOG_LIMIT=20
 
-# Memex Integration
-# Inside Docker, /app/ is the root for consolidated notes
+# =============================================================================
+# MEMEX STRUCTURE
+# =============================================================================
 MEMEX_DIR="$HOME/memex"
-ZETTELKASTEN_DIR="$HOME/memex/notes"
 SKILLS_DIR="skills/"
-
-# PARA Structure (Consolidated)
+ZETTELKASTEN_DIR="$HOME/memex/notes"
 INBOX_DIR="$HOME/memex/inbox"
 DAILY_DIR="$HOME/memex/daily"
 PROJECTS_DIR="$HOME/memex/projects"
@@ -52,15 +74,3 @@ AREAS_DIR="$HOME/memex/areas"
 RESOURCES_DIR="$HOME/memex/resources"
 ARCHIVES_DIR="$HOME/memex/archives"
 SYSTEM_DIR="$HOME/memex/system"
-
-# Identity Configuration
-MEMEX_USER="YourName"
-MEMEX_ASSISTANT="AgentName"
-RECIPIENT_ID="+1..." # For Signal/Telegram delivery
-
-# Harness Protocol Integrity & Authentication (HMAC-SHA256)
-PROTOCOL_ENFORCE_HMAC=false
-PROTOCOL_HMAC_SECRET="change-this-to-a-secure-random-string"
-
-# Neural Reasoning Cascade Order (Comma-separated keywords)
-PROVIDER_CASCADE="openrouter,openai,anthropic,groq,gemini-api,ollama"