---
name: subaiva-search
description: |
  Search the SubAIVA Knowledge Store — 1,627+ ingested documents with FTS5 BM25
  relevance scoring. Includes deep think results, platform KBs, research reports,
  entity files, axioms, .gemini/knowledge files, and architecture plans.

  WHEN TO USE:
  - "Search knowledge store for [topic]"
  - "What does Genesis know about [topic]?"
  - "Find research on [topic]"
  - "SubAIVA search [query]"
  - /subaiva-search [query]
  - Before any build or research task (CHECK-EXISTING FIRST — Rule 16)
  - When you need prior research, deep think results, or platform documentation
  - When verifying whether Genesis already has knowledge on a topic

  CAPABILITIES:
  - Full-text search with BM25 relevance scoring (FTS5, porter stemming)
  - Server-side category filtering (22 categories: genesis, research, entity, voice, axiom, etc.)
  - Knowledge store statistics (document counts, category breakdown, token usage)
  - Returns: title, summary, key_facts, source file path, category, BM25 score

  API ENDPOINT:
  - Search: POST https://subaiva.kinan-ae7.workers.dev/api/swarm/search
  - Stats:  GET  https://subaiva.kinan-ae7.workers.dev/api/swarm/stats
  - Auth:   Bearer dev-token-genesis-2026

allowed-tools:
  - Bash
---

# SubAIVA Knowledge Store Search

## Overview

The SubAIVA Knowledge Store is a Cloudflare Worker-backed search index containing 1,500+ ingested Genesis documents. It provides semantic search across deep think results, platform documentation, research reports, KG entities, axioms, session handoffs, strategy documents, and more.

This skill bridges the gap between Genesis agents and the knowledge store, enabling any agent to query prior work before building.

## API Details

| Field | Value |
|-------|-------|
| **Search endpoint** | `POST https://subaiva.kinan-ae7.workers.dev/api/swarm/search` |
| **Stats endpoint** | `GET https://subaiva.kinan-ae7.workers.dev/api/swarm/stats` |
| **Auth header** | `Authorization: Bearer dev-token-genesis-2026` |
| **Content type** | `application/json` |
| **Timeout** | 15 seconds recommended |

## Search — Basic Query

```bash
curl -s -X POST https://subaiva.kinan-ae7.workers.dev/api/swarm/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dev-token-genesis-2026" \
  -d '{"query": "YOUR SEARCH QUERY HERE", "limit": 5}'
```

### Request Body

```json
{
  "query": "telnyx voice widget architecture",
  "limit": 10
}
```

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `query` | string | Yes | — | Semantic search query. Matches against title, summary, and key_facts. |
| `limit` | integer | No | 10 | Maximum number of results to return. |

### Response Format

```json
{
  "results": [
    {
      "id": "doc_1772145719792_7przmj",
      "source": "Research reports/swarm_session17/TELNYX_VS_TWILIO_COST_COMPARISON.md",
      "title": "TELNYX_VS_TWILIO_COST_COMPARISON",
      "summary": "Telnyx and Twilio are compared in terms of pricing for Voice AI...",
      "key_facts": "- Telnyx offers 33% cheaper inbound calling rates...\n- WebRTC costs are ~25% lower...",
      "category": "genesis",
      "processed_at": 1772145733572
    }
  ]
}
```

### Response Fields

| Field | Description |
|-------|-------------|
| `id` | Unique document ID |
| `source` | Original file path within the Genesis repository |
| `title` | Document title (extracted during ingestion) |
| `summary` | AI-generated summary of the document content |
| `key_facts` | Bullet-point list of key facts extracted from the document |
| `category` | Document category (see categories below) |
| `processed_at` | Unix timestamp of when the document was ingested |

## Search — With Category Filter (Server-Side)

The API supports server-side category filtering via the `category` parameter:

```bash
curl -s -X POST https://subaiva.kinan-ae7.workers.dev/api/swarm/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dev-token-genesis-2026" \
  -d '{"query": "voice agent pricing", "category": "research", "limit": 10}'
```

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `category` | string | No | — | Server-side category filter (faster than client-side) |

## Stats — Knowledge Store Overview

```bash
curl -s https://subaiva.kinan-ae7.workers.dev/api/swarm/stats \
  -H "Authorization: Bearer dev-token-genesis-2026"
```

### Stats Response Format

```json
{
  "totalDocuments": 1567,
  "totalJobs": 66,
  "totalTokens": 2619512,
  "byCategory": [
    {"category": "entity", "count": 243},
    {"category": "genesis", "count": 241},
    {"category": "research", "count": 224},
    {"category": "documentation", "count": 166},
    {"category": "session_handoffs", "count": 152}
  ]
}
```

## Available Categories

| Category | Count | Description |
|----------|-------|-------------|
| `entity` | 243 | KG entity files |
| `genesis` | 241 | General Genesis system docs |
| `research` | 224 | Research reports |
| `documentation` | 166 | Platform and system documentation |
| `session_handoffs` | 152 | Session handoff summaries |
| `strategy` | 102 | Strategy documents |
| `ghl` | 85 | GoHighLevel platform docs |
| `axiom` | 67 | KG axiom files |
| `deep_think_memory` | 52 | Deep Think memory outputs |
| `prds` | 30 | Product Requirement Documents |
| `deep_think_session` | 26 | Deep Think session results |
| `aiva` | 23 | AIVA-related documents |
| `receptionistai` | 23 | ReceptionistAI product docs |
| `deep_think` | 19 | Deep Think general results |
| `sunaiva` | 13 | Sunaiva/Talking Widget docs |
| `architecture` | 12 | Architecture maps and designs |
| `cloudflare` | 7 | Cloudflare Workers/DO docs |
| `marketing` | 7 | Marketing strategies |
| `tradies` | 7 | Tradie-specific documents |
| `agileadapt` | 1 | AgileAdapt brand docs |

## Usage Examples

### Example 1: Pre-build knowledge check (Rule 16 compliance)

Before building any feature, search for prior work:

```bash
curl -s -X POST https://subaiva.kinan-ae7.workers.dev/api/swarm/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dev-token-genesis-2026" \
  -d '{"query": "cloudflare durable objects memory architecture", "limit": 5}' | \
  python3 -c "
import json, sys
data = json.load(sys.stdin)
results = data.get('results', [])
print(f'Found {len(results)} prior documents on this topic:')
for i, r in enumerate(results, 1):
    print(f'\n--- Result {i} ---')
    print(f'Title: {r[\"title\"]}')
    print(f'Source: {r[\"source\"]}')
    print(f'Category: {r[\"category\"]}')
    print(f'Summary: {r[\"summary\"][:300]}')
    if r.get('key_facts'):
        print(f'Key Facts: {r[\"key_facts\"][:300]}')
"
```

### Example 2: Find all deep think results on a topic

```bash
curl -s -X POST https://subaiva.kinan-ae7.workers.dev/api/swarm/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dev-token-genesis-2026" \
  -d '{"query": "revenue engine autonomous", "limit": 15}' | \
  python3 -c "
import json, sys
data = json.load(sys.stdin)
dt_results = [r for r in data.get('results', []) if 'deep_think' in r.get('category', '')]
print(f'Deep Think results: {len(dt_results)}')
for r in dt_results:
    print(f'  [{r[\"category\"]}] {r[\"title\"]} -> {r[\"source\"]}')
"
```

### Example 3: Quick formatted search (copy-paste ready)

```bash
curl -s -X POST https://subaiva.kinan-ae7.workers.dev/api/swarm/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dev-token-genesis-2026" \
  -d '{"query": "GHL API automation webhook", "limit": 5}' | \
  python3 -m json.tool
```

### Example 4: Search and extract just sources (for reading)

```bash
curl -s -X POST https://subaiva.kinan-ae7.workers.dev/api/swarm/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dev-token-genesis-2026" \
  -d '{"query": "AIVA constitution memory", "limit": 10}' | \
  python3 -c "
import json, sys
for r in json.load(sys.stdin).get('results', []):
    print(r['source'])
"
```

### Example 5: Get knowledge store health check

```bash
curl -s https://subaiva.kinan-ae7.workers.dev/api/swarm/stats \
  -H "Authorization: Bearer dev-token-genesis-2026" | \
  python3 -c "
import json, sys
s = json.load(sys.stdin)
print(f'Total documents: {s[\"totalDocuments\"]}')
print(f'Total tokens:    {s[\"totalTokens\"]:,}')
print(f'Ingestion jobs:  {s[\"totalJobs\"]}')
print(f'\nTop categories:')
for c in s.get('byCategory', [])[:10]:
    print(f'  {c[\"category\"]:25s} {c[\"count\"]:>5d} docs')
"
```

## Integration with Genesis Protocols

| Protocol | How This Skill Helps |
|----------|----------------------|
| **Rule 16: Check-Existing First** | Search before building to find prior work |
| **Rule 8: Research-First** | Query knowledge store for research reports on any topic |
| **Rule 10: Capability-First** | Check what platform docs are already indexed |
| **Rule 18: Platform-First** | Find existing SDK/MCP research before writing custom code |
| **Alpha Evolve** | Search for prior evolution cycle outputs and axioms |

## Error Handling

| HTTP Status | Meaning | Action |
|-------------|---------|--------|
| 200 | Success | Parse results normally |
| 401 | Unauthorized | Check Bearer token is `dev-token-genesis-2026` |
| 500 | Server error | Cloudflare Worker may be down; retry once, then check deployment |
| Timeout | Worker cold start | Retry after 2 seconds; first request may take longer |

## Notes

- Search uses FTS5 full-text indexing with BM25 relevance scoring (porter stemming)
- Results are ranked by BM25 score (higher = more relevant); the `limit` parameter controls count
- The `score` field in results shows the BM25 relevance rank
- The `source` field maps to the original file path in the Genesis repository
- `key_facts` is a newline-separated bullet list and is the most information-dense field
- For exact file reading after search, use the `source` path with the Read tool
- This endpoint is also available via the `genesis-core` MCP server tool `search_subaiva_knowledge`
