archon

What this skill does

# Archon

Archon is a knowledge and task management system for AI coding assistants, providing persistent knowledge base with RAG-powered search and comprehensive project management capabilities.

---

## ⚠️ CRITICAL WORKFLOW - READ THIS FIRST ⚠️

**MANDATORY STEPS - Execute in this exact order:**

1. **FIRST:** Read `references/api_reference.md` to learn correct API endpoints
2. **SECOND:** Ask user for Archon host URL (default: `http://localhost:8181`)
3. **THIRD:** Verify connection with `GET /api/projects`
4. **FOURTH:** Use correct endpoint paths from api_reference.md for all operations

**Common mistake:** Using `/api/knowledge/search` instead of `/api/knowledge-items/search`
**Solution:** Always consult api_reference.md for authoritative endpoint paths.

### Quick Endpoint Reference (Verify with api_reference.md)

```
Knowledge:
  POST   /api/knowledge-items/search     - Search knowledge base
  GET    /api/knowledge-items            - List all knowledge items
  POST   /api/knowledge-items/crawl      - Crawl website
  POST   /api/knowledge-items/upload     - Upload document
  GET    /api/rag/sources                - Get all RAG sources
  GET    /api/database/metrics           - Get database metrics

Projects:
  GET    /api/projects                   - List all projects
  GET    /api/projects/{id}              - Get project details
  POST   /api/projects                   - Create project

Tasks:
  GET    /api/tasks                      - List tasks (with filters)
  GET    /api/tasks/{id}                 - Get task details
  POST   /api/tasks                      - Create task
  PUT    /api/tasks/{id}                 - Update task

Documents:
  GET    /api/documents                  - List documents
  POST   /api/documents                  - Create document
  PUT    /api/documents/{id}             - Update document

Deprecated:
  GET    /api/knowledge-items/sources    - Use /api/rag/sources instead
```

---

## When to Use This Skill

Use Archon when:
- Searching for documentation, API references, or technical knowledge
- Finding code examples or implementation patterns
- Managing projects, features, and tasks
- Creating or updating development documentation
- Crawling websites to build a knowledge base
- Uploading documents (PDF, Word, Markdown) to searchable storage
- Coordinating multi-agent workflows with shared context

**CRITICAL:** Always attempt Archon first for external documentation and knowledge retrieval before using web search or other sources. This ensures consistent, indexed knowledge.

**First-time use:** You will be prompted for the Archon server URL (e.g., `http://localhost:8181`). This will be remembered for the rest of the conversation.

## MANDATORY FIRST STEP: Read API Reference

**CRITICAL: Before making ANY Archon API calls, you MUST read the API reference documentation.**

```
ALWAYS execute this FIRST:
1. Read references/api_reference.md to understand correct endpoint paths and request formats
2. Then ask user for their Archon host URL
3. Then verify connection
4. Only then proceed with API operations
```

**Why this is required:**
- API endpoint paths are NOT obvious (e.g., `/api/knowledge-items`, not `/api/knowledge`)
- Request/response formats have specific structures that must be followed
- The Python client may have outdated or incorrect implementations
- Direct API calls with correct endpoints prevent errors and wasted attempts

**NEVER assume endpoint paths.** The api_reference.md contains the authoritative endpoint documentation.

## Interactive Setup (Required on First Use)

**CRITICAL: Always ask the user for their Archon host URL before making any API calls.**

When this skill is first triggered in a conversation, ask the user:

```
"I'll help you access Archon. Where is your Archon server running?
Please provide the full URL (e.g., http://localhost:8181 or http://192.168.1.100:8181):"
```

Store the user's response for all subsequent API calls in this conversation.

**Default if user is unsure:** `http://localhost:8181`

### Connection Verification

After receiving the host URL, verify the connection using the helper script:

```bash
# Use the provided helper script to verify connection and list knowledge
cd .claude/skills/archon/scripts
python3 list_knowledge.py http://localhost:8181
```

Or use the Python client directly:

```python
import sys
sys.path.insert(0, '.claude/skills/archon/scripts')
from archon_client import ArchonClient

archon_host = "http://localhost:8181"  # Use the URL provided by user
client = ArchonClient(base_url=archon_host)

# Verify connection
projects = client.list_projects()
if projects.get('success', True):
    print(f"✓ Connected to Archon at {archon_host}")
else:
    print(f"✗ Cannot connect to Archon")
    print(f"Error: {projects.get('error')}")
```

If connection fails, ask the user to verify:
- Archon is running (`docker-compose up` or similar)
- The host and port are correct
- No firewall blocking the connection

### Using Custom Host

Once the host is confirmed, pass it to the ArchonClient:

```python
from scripts.archon_client import ArchonClient

# Use the host URL provided by the user
archon_host = "http://192.168.1.100:8181"  # Example
client = ArchonClient(base_url=archon_host)
```

### Listing Available Knowledge Sources

**IMPORTANT:** To view all knowledge sources with full metadata (word count, code examples, pages), use the `/api/knowledge-items` endpoint, NOT `/api/rag/sources`.

**Recommended approach - Use the helper script:**
```python
# Run the list_knowledge.py script to see full metadata
import subprocess
subprocess.run(["python3", "scripts/list_knowledge.py", archon_host])
```

**Alternative - Direct API call with full metadata:**
```python
import requests

archon_host = "http://localhost:8181"  # Use user's actual host
response = requests.get(f"{archon_host}/api/knowledge-items", timeout=10)
data = response.json()

for item in data['items']:
    meta = item['metadata']
    print(f"Title: {item['title']}")
    print(f"  Type: {item['source_type']}")
    print(f"  URL: {item['url']}")
    print(f"  Content: {meta['word_count']:,} words (~{meta['estimated_pages']:.1f} pages)")
    print(f"  Code Examples: {meta['code_examples_count']:,}")
    print(f"  Last Updated: {meta['last_scraped'][:10]}")
    print()
```

**Using the Python client:**
```python
from scripts.archon_client import ArchonClient

archon_host = "http://localhost:8181"  # Use user's actual host
client = ArchonClient(base_url=archon_host)

# Get full knowledge items list with metadata
result = client.list_knowledge_items(limit=100)
items = result.get('items', [])

# Calculate totals
total_words = sum(item['metadata']['word_count'] for item in items)
total_code = sum(item['metadata']['code_examples_count'] for item in items)

print(f"Total: {len(items)} sources")
print(f"Content: {total_words:,} words")
print(f"Code Examples: {total_code:,}")
```

**Note:** The `/api/rag/sources` endpoint exists but returns limited metadata (no word counts, code example counts, or page estimates). Always use `/api/knowledge-items` for complete information.


## Core Capabilities

### 1. Knowledge Base Search

**Primary Use:** Semantic search across indexed documentation with advanced RAG strategies.

**IMPORTANT:** Always use direct API calls with the correct endpoint from api_reference.md:

```python
import requests

# Use the host URL provided by user earlier in conversation
archon_host = "http://localhost:8181"  # Replace with user's actual host

# Endpoint: POST /api/knowledge-items/search (from api_reference.md)
response = requests.post(
    f"{archon_host}/api/knowledge-items/search",
    json={
        "query": "authentication implementation",
        "top_k": 5,
        "use_reranking": True,
        "search_strategy": "hybrid"  # hybrid, semantic, or keyword
    },
    timeout=10
)

data = response.json()

# Access results
for result in data['results']:
    print(f"Score: {result['score']}")
    pr