Fix Supabase key validation and consolidate frontend state management

.env.example

@@ -5,9 +5,22 @@
 # https://supabase.com/dashboard/project/<your project ID>/settings/api
 SUPABASE_URL=
 
-# Get your SUPABASE_SERVICE_KEY from the API Keys section of your Supabase project settings -
-# https://supabase.com/dashboard/project/<your project ID>/settings/api-keys
-# On this page it is called the service_role secret.
+# ⚠️ CRITICAL: You MUST use the SERVICE ROLE key, NOT the Anon key! ⚠️
+# 
+# COMMON MISTAKE: Using the anon (public) key will cause ALL saves to fail with "permission denied"!
+#
+# How to get the CORRECT key:
+# 1. Go to: https://supabase.com/dashboard/project/<your project ID>/settings/api
+# 2. In the Settings menu, click on "API keys" 
+# 3. Find "Project API keys" section
+# 4. You will see TWO keys - choose carefully:
+#    ❌ anon (public): WRONG - This is shorter, starts with "eyJhbGc..." and contains "anon" in the JWT
+#    ✅ service_role (secret): CORRECT - This is longer and contains "service_role" in the JWT
+#
+# The service_role key is typically much longer than the anon key.
+# If you see errors like "Failed to save" or "Permission denied", you're using the wrong key!
+#
+# On the Supabase dashboard, it's labeled as "service_role" under "Project API keys"
 SUPABASE_SERVICE_KEY=
 
 # Optional: Set log level for debugging

README.md

@@ -21,7 +21,7 @@
 Archon is the **command center** for AI coding assistants. For you, it's a sleek interface to manage knowledge, context, and tasks for your projects. For the AI coding assistant(s), it's a **Model Context Protocol (MCP) server** to collaborate on and leverage the same knowledge, context, and tasks. Connect Claude Code, Kiro, Cursor, Windsurf, etc. to give your AI agents access to:
 
 - **Your documentation** (crawled websites, uploaded PDFs/docs)
-- **Smart search capabilities** with advanced RAG strategies  
+- **Smart search capabilities** with advanced RAG strategies
 - **Task management** integrated with your knowledge base
 - **Real-time updates** as you add new content and collaborate with your coding assistant on tasks
 - **Much more** coming soon to build Archon into an integrated environment for all context engineering
@@ -40,19 +40,22 @@ This new vision for Archon replaces the old one (the agenteer). Archon used to b
 ## Quick Start
 
 ### Prerequisites
+
 - [Docker Desktop](https://www.docker.com/products/docker-desktop/)
 - [Supabase](https://supabase.com/) account (free tier or local Supabase both work)
 - [OpenAI API key](https://platform.openai.com/api-keys) (Gemini and Ollama are supported too!)
 
 ### Setup Instructions
 
 1. **Clone Repository**:
+
    ```bash
    git clone https://github.com/coleam00/archon.git
    cd archon
    ```
 
 2. **Environment Configuration**:
+
    ```bash
    cp .env.example .env
    # Edit .env and add your Supabase credentials:
@@ -65,10 +68,11 @@ This new vision for Archon replaces the old one (the agenteer). Archon used to b
 3. **Database Setup**: In your [Supabase project](https://supabase.com/dashboard) SQL Editor, copy, paste, and execute the contents of `migration/complete_setup.sql`
 
 4. **Start Services**:
+
    ```bash
    docker-compose up --build -d
    ```
-   
+
    This starts the core microservices:
    - **Server**: Core API and business logic (Port: 8181)
    - **MCP Server**: Protocol interface for AI clients (Port: 8051)
@@ -90,17 +94,18 @@ If you need to completely reset your database and start fresh:
 <summary>⚠️ <strong>Reset Database - This will delete ALL data for Archon!</strong></summary>
 
 1. **Run Reset Script**: In your Supabase SQL Editor, run the contents of `migration/RESET_DB.sql`
-   
+
    ⚠️ WARNING: This will delete all Archon specific tables and data! Nothing else will be touched in your DB though.
 
 2. **Rebuild Database**: After reset, run `migration/complete_setup.sql` to create all the tables again.
 
 3. **Restart Services**:
+
    ```bash
    docker-compose up -d
    ```
 
-4. **Reconfigure**: 
+4. **Reconfigure**:
    - Select your LLM/embedding provider and set the API key again
    - Re-upload any documents or re-crawl websites
 
@@ -121,36 +126,40 @@ Once everything is running:
 
 ### Core Services
 
-| Service | Container Name | Default URL | Purpose |
-|---------|---------------|-------------|---------|
-| **Web Interface** | archon-ui | http://localhost:3737 | Main dashboard and controls |
-| **API Service** | archon-server | http://localhost:8181 | Web crawling, document processing |
-| **MCP Server** | archon-mcp | http://localhost:8051 | Model Context Protocol interface |
-| **Agents Service** | archon-agents | http://localhost:8052 | AI/ML operations, reranking |
+| Service            | Container Name | Default URL           | Purpose                           |
+| ------------------ | -------------- | --------------------- | --------------------------------- |
+| **Web Interface**  | archon-ui      | http://localhost:3737 | Main dashboard and controls       |
+| **API Service**    | archon-server  | http://localhost:8181 | Web crawling, document processing |
+| **MCP Server**     | archon-mcp     | http://localhost:8051 | Model Context Protocol interface  |
+| **Agents Service** | archon-agents  | http://localhost:8052 | AI/ML operations, reranking       |
 
 ## What's Included
 
 ### 🧠 Knowledge Management
+
 - **Smart Web Crawling**: Automatically detects and crawls entire documentation sites, sitemaps, and individual pages
 - **Document Processing**: Upload and process PDFs, Word docs, markdown files, and text documents with intelligent chunking
 - **Code Example Extraction**: Automatically identifies and indexes code examples from documentation for enhanced search
 - **Vector Search**: Advanced semantic search with contextual embeddings for precise knowledge retrieval
 - **Source Management**: Organize knowledge by source, type, and tags for easy filtering
 
-### 🤖 AI Integration  
+### 🤖 AI Integration
+
 - **Model Context Protocol (MCP)**: Connect any MCP-compatible client (Claude Code, Cursor, even non-AI coding assistants like Claude Desktop)
 - **10 MCP Tools**: Comprehensive yet simple set of tools for RAG queries, task management, and project operations
 - **Multi-LLM Support**: Works with OpenAI, Ollama, and Google Gemini models
 - **RAG Strategies**: Hybrid search, contextual embeddings, and result reranking for optimal AI responses
 - **Real-time Streaming**: Live responses from AI agents with progress tracking
 
 ### 📋 Project & Task Management
+
 - **Hierarchical Projects**: Organize work with projects, features, and tasks in a structured workflow
-- **AI-Assisted Creation**: Generate project requirements and tasks using integrated AI agents  
+- **AI-Assisted Creation**: Generate project requirements and tasks using integrated AI agents
 - **Document Management**: Version-controlled documents with collaborative editing capabilities
 - **Progress Tracking**: Real-time updates and status management across all project activities
 
 ### 🔄 Real-time Collaboration
+
 - **WebSocket Updates**: Live progress tracking for crawling, processing, and AI operations
 - **Multi-user Support**: Collaborative knowledge building and project management
 - **Background Processing**: Asynchronous operations that don't block the user interface
@@ -184,17 +193,17 @@ Archon uses true microservices architecture with clear separation of concerns:
 
 ### Service Responsibilities
 
-| Service | Location | Purpose | Key Features |
-|---------|----------|---------|--------------|
-| **Frontend** | `archon-ui-main/` | Web interface and dashboard | React, TypeScript, TailwindCSS, Socket.IO client |
-| **Server** | `python/src/server/` | Core business logic and APIs | FastAPI, service layer, Socket.IO broadcasts, all ML/AI operations |
-| **MCP Server** | `python/src/mcp/` | MCP protocol interface | Lightweight HTTP wrapper, 10 MCP tools, session management |
-| **Agents** | `python/src/agents/` | PydanticAI agent hosting | Document and RAG agents, streaming responses |
+| Service        | Location             | Purpose                      | Key Features                                                       |
+| -------------- | -------------------- | ---------------------------- | ------------------------------------------------------------------ |
+| **Frontend**   | `archon-ui-main/`    | Web interface and dashboard  | React, TypeScript, TailwindCSS, Socket.IO client                   |
+| **Server**     | `python/src/server/` | Core business logic and APIs | FastAPI, service layer, Socket.IO broadcasts, all ML/AI operations |
+| **MCP Server** | `python/src/mcp/`    | MCP protocol interface       | Lightweight HTTP wrapper, 10 MCP tools, session management         |
+| **Agents**     | `python/src/agents/` | PydanticAI agent hosting     | Document and RAG agents, streaming responses                       |
 
 ### Communication Patterns
 
 - **HTTP-based**: All inter-service communication uses HTTP APIs
-- **Socket.IO**: Real-time updates from Server to Frontend  
+- **Socket.IO**: Real-time updates from Server to Frontend
 - **MCP Protocol**: AI clients connect to MCP Server via SSE or stdio
 - **No Direct Imports**: Services are truly independent with no shared code dependencies
 
@@ -208,8 +217,9 @@ Archon uses true microservices architecture with clear separation of concerns:
 ## 🔧 Configuring Custom Ports & Hostname
 
 By default, Archon services run on the following ports:
+
 - **Archon-UI**: 3737
-- **Archon-Server**: 8181  
+- **Archon-Server**: 8181
 - **Archon-MCP**: 8051
 - **Archon-Agents**: 8052
 - **Archon-Docs**: 3838 (optional)
@@ -228,6 +238,7 @@ ARCHON_DOCS_PORT=3838
 ```
 
 Example: Running on different ports:
+
 ```bash
 ARCHON_SERVER_PORT=8282
 ARCHON_MCP_PORT=8151
@@ -248,11 +259,13 @@ HOST=myserver.com      # Use public domain
 ```
 
 This is useful when:
+
 - Running Archon on a different machine and accessing it remotely
 - Using a custom domain name for your installation
 - Deploying in a network environment where `localhost` isn't accessible
 
 After changing hostname or ports:
+
 1. Restart Docker containers: `docker-compose down && docker-compose up -d`
 2. Access the UI at: `http://${HOST}:${ARCHON_UI_PORT}`
 3. Update your AI client configuration with the new hostname and MCP port
@@ -265,7 +278,7 @@ For development with hot reload:
 # Backend services (with auto-reload)
 docker-compose up archon-server archon-mcp archon-agents --build
 
-# Frontend (with hot reload) 
+# Frontend (with hot reload)
 cd archon-ui-main && npm run dev
 
 # Documentation (with hot reload)

archon-ui-main/Dockerfile

@@ -22,4 +22,4 @@ COPY . .
 EXPOSE 5173
 
 # Start Vite dev server with host binding for Docker
-CMD ["npm", "run", "dev", "--", "--host", "0.0.0.0"] 
+CMD ["npm", "run", "dev", "--", "--host", "0.0.0.0"]

archon-ui-main/src/components/BackendStartupError.tsx

@@ -0,0 +1,74 @@
+import React from 'react';
+import { AlertCircle, Terminal, RefreshCw } from 'lucide-react';
+
+export const BackendStartupError: React.FC = () => {
+  const handleRetry = () => {
+    // Reload the page to retry
+    window.location.reload();
+  };
+
+  return (
+    <div className="fixed inset-0 z-[10000] bg-black/90 backdrop-blur-sm flex items-center justify-center p-8">
+      <div className="max-w-2xl w-full">
+        <div className="bg-red-950/50 border-2 border-red-500/50 rounded-lg p-8 shadow-2xl backdrop-blur-md">
+          <div className="flex items-start gap-4">
+            <AlertCircle className="w-8 h-8 text-red-500 flex-shrink-0 mt-1" />
+            <div className="space-y-4 flex-1">
+              <h2 className="text-2xl font-bold text-red-100">
+                Backend Service Startup Failure
+              </h2>
+
+              <p className="text-red-200">
+                The Archon backend service failed to start. This is typically due to a configuration issue.
+              </p>
+
+              <div className="bg-black/50 rounded-lg p-4 border border-red-900/50">
+                <div className="flex items-center gap-2 mb-3 text-red-300">
+                  <Terminal className="w-5 h-5" />
+                  <span className="font-semibold">Check Docker Logs</span>
+                </div>
+                <p className="text-red-100 font-mono text-sm mb-3">
+                  Check the <span className="text-red-400 font-bold">Archon-Server</span> logs in Docker Desktop for detailed error information.
+                </p>
+                <div className="space-y-2 text-xs text-red-300">
+                  <p>1. Open Docker Desktop</p>
+                  <p>2. Go to Containers tab</p>
+                  <p>3. Click on <span className="text-red-400 font-semibold">Archon-Server</span></p>
+                  <p>4. View the logs for the specific error message</p>
+                </div>
+              </div>
+
+              <div className="bg-yellow-950/30 border border-yellow-700/30 rounded-lg p-3">
+                <p className="text-yellow-200 text-sm">
+                  <strong>Common issue:</strong> Using an ANON key instead of SERVICE key in your .env file
+                </p>
+              </div>
+
+              <div className="pt-4 border-t border-red-900/30">
+                <p className="text-red-300 text-sm">
+                  After fixing the issue in your .env file, recreate the Docker containers:
+                </p>
+                <code className="block mt-2 p-2 bg-black/70 rounded text-red-100 font-mono text-sm">
+                  docker compose down && docker compose up -d
+                </code>
+                <p className="text-red-300 text-xs mt-2">
+                  Note: Use 'down' and 'up', not 'restart' - containers need to be recreated to load new environment variables
+                </p>
+              </div>
+
+              <div className="flex justify-center pt-4">
+                <button
+                  onClick={handleRetry}
+                  className="flex items-center gap-2 px-4 py-2 bg-red-600/20 hover:bg-red-600/30 border border-red-500/50 rounded-lg text-red-100 transition-colors"
+                >
+                  <RefreshCw className="w-4 h-4" />
+                  Retry Connection
+                </button>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+};

archon-ui-main/src/components/layouts/MainLayout.tsx

@@ -6,6 +6,7 @@ import { X } from 'lucide-react';
 import { useToast } from '../../contexts/ToastContext';
 import { credentialsService } from '../../services/credentialsService';
 import { isLmConfigured } from '../../utils/onboarding';
+import { BackendStartupError } from '../BackendStartupError';
 /**
  * Props for the MainLayout component
  */
@@ -29,13 +30,14 @@ export const MainLayout: React.FC<MainLayoutProps> = ({
   const navigate = useNavigate();
   const location = useLocation();
   const [backendReady, setBackendReady] = useState(false);
+  const [backendStartupFailed, setBackendStartupFailed] = useState(false);
 
   // Check backend readiness
   useEffect(() => {
 
     const checkBackendHealth = async (retryCount = 0) => {
-      const maxRetries = 10; // Increased retries for initialization
-      const retryDelay = 1000;
+      const maxRetries = 3; // 3 retries total
+      const retryDelay = 1500; // 1.5 seconds between retries
 
       try {
         // Create AbortController for proper timeout handling
@@ -58,6 +60,7 @@ export const MainLayout: React.FC<MainLayoutProps> = ({
           if (healthData.ready === true) {
             console.log('✅ Backend is fully initialized');
             setBackendReady(true);
+            setBackendStartupFailed(false);
           } else {
             // Backend is starting up but not ready yet
             console.log(`🔄 Backend initializing... (attempt ${retryCount + 1}/${maxRetries}):`, healthData.message || 'Loading credentials...');
@@ -66,9 +69,10 @@ export const MainLayout: React.FC<MainLayoutProps> = ({
             if (retryCount < maxRetries) {
               setTimeout(() => {
                 checkBackendHealth(retryCount + 1);
-              }, retryDelay); // Constant 1s retry during initialization
+              }, retryDelay); // Constant 1.5s retry during initialization
             } else {
-              console.warn('Backend initialization taking too long - skipping credential check');
+              console.warn('Backend initialization taking too long - proceeding anyway');
+              // Don't mark as failed yet, just not fully ready
               setBackendReady(false);
             }
           }
@@ -80,16 +84,20 @@ export const MainLayout: React.FC<MainLayoutProps> = ({
         const errorMessage = error instanceof Error 
           ? (error.name === 'AbortError' ? 'Request timeout (5s)' : error.message)
           : 'Unknown error';
-        console.log(`Backend not ready yet (attempt ${retryCount + 1}/${maxRetries}):`, errorMessage);
+        // Only log after first attempt to reduce noise during normal startup
+        if (retryCount > 0) {
+          console.log(`Backend not ready yet (attempt ${retryCount + 1}/${maxRetries}):`, errorMessage);
+        }
 
         // Retry if we haven't exceeded max retries
         if (retryCount < maxRetries) {
           setTimeout(() => {
             checkBackendHealth(retryCount + 1);
           }, retryDelay * Math.pow(1.5, retryCount)); // Exponential backoff for connection errors
         } else {
-          console.warn('Backend not ready after maximum retries - skipping credential check');
+          console.error('Backend startup failed after maximum retries - showing error message');
           setBackendReady(false);
+          setBackendStartupFailed(true);
         }
       }
     };
@@ -99,11 +107,16 @@ export const MainLayout: React.FC<MainLayoutProps> = ({
     setTimeout(() => {
       checkBackendHealth();
     }, 1000); // Wait 1 second for initial app startup
-  }, [showToast, navigate]); // Removed backendReady from dependencies to prevent double execution
+  }, []); // Empty deps - only run once on mount
 
   // Check for onboarding redirect after backend is ready
   useEffect(() => {
     const checkOnboarding = async () => {
+      // Skip if backend failed to start
+      if (backendStartupFailed) {
+        return;
+      }
+
       // Skip if not ready, already on onboarding, or already dismissed
       if (!backendReady || location.pathname === '/onboarding') {
         return;
@@ -152,9 +165,12 @@ export const MainLayout: React.FC<MainLayoutProps> = ({
     };
 
     checkOnboarding();
-  }, [backendReady, location.pathname, navigate, showToast]);
+  }, [backendReady, backendStartupFailed, location.pathname, navigate, showToast]);
 
   return <div className="relative min-h-screen bg-white dark:bg-black overflow-hidden">
+      {/* Show backend startup error if backend failed to start */}
+      {backendStartupFailed && <BackendStartupError />}
+
       {/* Fixed full-page background grid that doesn't scroll */}
       <div className="fixed inset-0 neon-grid pointer-events-none z-0"></div>
       {/* Floating Navigation */}