@heretek-ai/epistemic-swarm 0.2.0 → 0.2.3

package/skills/epistemic_search/scripts/fetch.py

@@ -0,0 +1,157 @@
+#!/usr/bin/env python3
+"""
+Zero-API-Key Web Content Fetcher with Automatic Content-Addressed SHA-256 Caching.
+Fetches web content, cleans HTML to readable Markdown, and persists directly into
+.research/sources/<sha256>.md for epistemic auditability.
+"""
+
+import sys
+import os
+import re
+import json
+import urllib.request
+import urllib.parse
+from html.parser import HTMLParser
+
+# Add project root to sys.path to import SourceHasher
+PKG_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "..", ".."))
+if PKG_ROOT not in sys.path:
+    sys.path.insert(0, PKG_ROOT)
+
+try:
+    from skills.research_cache.hasher import SourceHasher
+except ImportError:
+    SourceHasher = None
+
+USER_AGENT = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+
+class HTMLToMarkdownExtractor(HTMLParser):
+    def __init__(self):
+        super().__init__()
+        self.in_script_or_style = False
+        self.title = ""
+        self.in_title = False
+        self.text_chunks = []
+        self.headings = []
+
+    def handle_starttag(self, tag, attrs):
+        if tag in ("script", "style", "noscript", "svg", "header", "footer", "nav"):
+            self.in_script_or_style = True
+        elif tag == "title":
+            self.in_title = True
+        elif tag in ("h1", "h2", "h3", "h4", "h5", "h6"):
+            self.text_chunks.append(f"\n\n{'#' * int(tag[1])} ")
+        elif tag in ("p", "div", "article", "section"):
+            self.text_chunks.append("\n\n")
+        elif tag == "li":
+            self.text_chunks.append("\n- ")
+        elif tag == "br":
+            self.text_chunks.append("\n")
+
+    def handle_endtag(self, tag):
+        if tag in ("script", "style", "noscript", "svg", "header", "footer", "nav"):
+            self.in_script_or_style = False
+        elif tag == "title":
+            self.in_title = False
+        elif tag in ("p", "div", "article", "section"):
+            self.text_chunks.append("\n")
+
+    def handle_data(self, data):
+        if self.in_script_or_style:
+            return
+        if self.in_title:
+            self.title += data
+        else:
+            self.text_chunks.append(data)
+
+    def get_markdown(self) -> str:
+        raw_text = "".join(self.text_chunks)
+        # Clean multiple blank lines
+        clean_text = re.sub(r"\n{3,}", "\n\n", raw_text).strip()
+        return clean_text
+
+def fetch_and_cache(url: str, research_dir: str = ".research") -> str:
+    headers = {
+        "User-Agent": USER_AGENT,
+        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+        "Accept-Language": "en-US,en;q=0.5",
+    }
+    req = urllib.request.Request(url, headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=20) as resp:
+            content_type = resp.headers.get("Content-Type", "")
+            raw_bytes = resp.read()
+            html = raw_bytes.decode("utf-8", errors="replace")
+    except Exception as e:
+        sys.stderr.write(f"[epistemic-fetch] Error fetching URL {url}: {e}\n")
+        return f"Error fetching {url}: {e}"
+
+    parser = HTMLToMarkdownExtractor()
+    parser.feed(html)
+    page_title = parser.title.strip() or url
+    body_markdown = parser.get_markdown()
+
+    # Cache into .research/sources/<sha256>.md
+    sha256_hash = "uncached"
+    cache_file = "not saved"
+    if SourceHasher:
+        from pathlib import Path
+        hasher = SourceHasher(base_dir=Path(research_dir))
+        sha256_hash = hasher.store_source(
+            url=url,
+            title=page_title,
+            content=body_markdown
+        )
+        cache_file = str(hasher.sources_dir / f"{sha256_hash}.md")
+    else:
+        import hashlib
+        sha256_hash = hashlib.sha256(body_markdown.encode("utf-8")).hexdigest()
+
+    output = []
+    output.append(f"<!-- EPISTEMIC_SOURCE_HASH: {sha256_hash} -->")
+    output.append(f"<!-- CACHED_AT: {cache_file} -->")
+    output.append(f"# {page_title}\n")
+    output.append(f"**Source URL:** {url}")
+    output.append(f"**Content SHA-256:** `{sha256_hash}`")
+    output.append(f"**Verification Tag:** `[VERIFIED: {sha256_hash[:16]}]`\n")
+    output.append(body_markdown)
+
+    return "\n".join(output)
+
+def main():
+    url = ""
+    research_dir = ".research"
+
+    if not sys.stdin.isatty():
+        try:
+            stdin_data = sys.stdin.read().strip()
+            if stdin_data:
+                try:
+                    payload = json.loads(stdin_data)
+                    url = payload.get("url", "")
+                    research_dir = payload.get("research_dir", research_dir)
+                except json.JSONDecodeError:
+                    url = stdin_data
+        except Exception:
+            pass
+
+    args = sys.argv[1:]
+    idx = 0
+    while idx < len(args):
+        arg = args[idx]
+        if arg == "--dir" and idx + 1 < len(args):
+            research_dir = args[idx + 1]
+            idx += 1
+        elif not url and not arg.startswith("--"):
+            url = arg
+        idx += 1
+
+    if not url:
+        sys.stderr.write("Usage: fetch.py [options] <url>\nOr pipe JSON: echo '{\"url\":\"https://...\"}' | fetch.py\n")
+        sys.exit(1)
+
+    result = fetch_and_cache(url=url, research_dir=research_dir)
+    print(result)
+
+if __name__ == "__main__":
+    main()

package/skills/epistemic_search/scripts/search.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""
+Zero-API-Key Web Search Engine for IUMBTEMS.
+DuckDuckGo HTML/lite parser with domain filtering and Claude Code XML formatting.
+"""
+
+import sys
+import json
+import re
+import urllib.request
+import urllib.parse
+from typing import List, Dict, Optional
+
+USER_AGENT = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+
+def search_duckduckgo(
+    query: str,
+    allowed_domains: Optional[List[str]] = None,
+    blocked_domains: Optional[List[str]] = None,
+    max_results: int = 10
+) -> List[Dict[str, str]]:
+    """Execute search query against DuckDuckGo Lite without API keys."""
+    effective_query = query.strip()
+    if allowed_domains:
+        domain_filters = " " + " OR ".join(f"site:{d}" for d in allowed_domains)
+        effective_query += domain_filters
+    if blocked_domains:
+        domain_filters = " " + " ".join(f"-site:{d}" for d in blocked_domains)
+        effective_query += domain_filters
+
+    url = "https://lite.duckduckgo.com/lite/"
+    data = urllib.parse.urlencode({"q": effective_query}).encode("utf-8")
+    headers = {
+        "User-Agent": USER_AGENT,
+        "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+        "Accept-Language": "en-US,en;q=0.5",
+        "Referer": "https://lite.duckduckgo.com/",
+    }
+
+    req = urllib.request.Request(url, data=data, headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            html = resp.read().decode("utf-8", errors="replace")
+    except Exception as e:
+        sys.stderr.write(f"[epistemic-search] Network error fetching search results: {e}\n")
+        return []
+
+    # Parse result links and snippets from DuckDuckGo Lite table rows
+    links = re.findall(
+        r"<a[^>]*href=['\"]([^'\"]+)['\"][^>]*class=['\"]result-link['\"][^>]*>(.*?)</a>",
+        html,
+        re.DOTALL
+    )
+    snippets = re.findall(
+        r"<td[^>]+class=['\"]result-snippet['\"][^>]*>(.*?)</td>",
+        html,
+        re.DOTALL
+    )
+
+    results = []
+    for (href, title_html), snip_html in zip(links, snippets):
+        # Unwrap DuckDuckGo redirect if present
+        m = re.search(r"uddg=([^&]+)", href)
+        if m:
+            clean_url = urllib.parse.unquote(m.group(1))
+        else:
+            clean_url = href
+
+        if not clean_url.startswith("http"):
+            continue
+
+        clean_title = re.sub(r"<[^>]+>", "", title_html).strip()
+        clean_snippet = re.sub(r"<[^>]+>", "", snip_html).strip()
+
+        # Check domain filtering manually in case DDG syntax didn't catch all
+        parsed_url = urllib.parse.urlparse(clean_url)
+        hostname = parsed_url.hostname or ""
+        if allowed_domains and not any(hostname == d or hostname.endswith("." + d) for d in allowed_domains):
+            continue
+        if blocked_domains and any(hostname == d or hostname.endswith("." + d) for d in blocked_domains):
+            continue
+
+        results.append({
+            "title": clean_title,
+            "url": clean_url,
+            "snippet": clean_snippet
+        })
+
+        if len(results) >= max_results:
+            break
+
+    return results
+
+def format_xml(results: List[Dict[str, str]]) -> str:
+    """Format results as Claude Code <search_results> XML."""
+    lines = ["<search_results>"]
+    for r in results:
+        lines.append("  <result>")
+        lines.append(f"    <title>{urllib.parse.quote(r['title'])}</title>")
+        lines.append(f"    <url>{r['url']}</url>")
+        lines.append(f"    <snippet>{r['snippet']}</snippet>")
+        lines.append("  </result>")
+    lines.append("</search_results>")
+    return "\n".join(lines)
+
+def main():
+    query = ""
+    allowed_domains = None
+    blocked_domains = None
+    output_json = False
+
+    # Check stdin first
+    if not sys.stdin.isatty():
+        try:
+            stdin_data = sys.stdin.read().strip()
+            if stdin_data:
+                try:
+                    payload = json.loads(stdin_data)
+                    query = payload.get("query", "")
+                    allowed_domains = payload.get("allowed_domains")
+                    blocked_domains = payload.get("blocked_domains")
+                except json.JSONDecodeError:
+                    query = stdin_data
+        except Exception:
+            pass
+
+    # Command line args override
+    args = sys.argv[1:]
+    idx = 0
+    while idx < len(args):
+        arg = args[idx]
+        if arg == "--json":
+            output_json = True
+        elif arg == "--allowed-domain" and idx + 1 < len(args):
+            allowed_domains = allowed_domains or []
+            allowed_domains.append(args[idx + 1])
+            idx += 1
+        elif arg == "--blocked-domain" and idx + 1 < len(args):
+            blocked_domains = blocked_domains or []
+            blocked_domains.append(args[idx + 1])
+            idx += 1
+        elif not query and not arg.startswith("--"):
+            query = arg
+        idx += 1
+
+    if not query:
+        sys.stderr.write("Usage: search.py [options] <query>\nOr pipe JSON: echo '{\"query\":\"...\"}' | search.py\n")
+        sys.exit(1)
+
+    results = search_duckduckgo(
+        query=query,
+        allowed_domains=allowed_domains,
+        blocked_domains=blocked_domains
+    )
+
+    if output_json:
+        print(json.dumps(results, indent=2))
+    else:
+        print(format_xml(results))
+
+if __name__ == "__main__":
+    main()

package/skills/oss_scout/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: oss-scout
+description: Open-source software discovery, dependency vetting, and clean-room implementation scouting. Evaluates GitHub repositories, package ecosystems, licenses, and architecture to discover code to adopt or borrow.
+---
+
+# Open Source Scout & Clean-Room Harvesting Engine
+
+Scout the open-source software ecosystem to discover mature libraries, reference implementations, and algorithms for research-based development.
+The scout deploys a **Discovery Scout (Thesis)** to find high-performance implementations and a **Licensing & Bloat Red-Teamer (Antithesis)** to protect your project against viral copyleft, unmaintained abandonware, and security CVEs.
+
+## 1. Invoking an Open Source Scout
+
+Search for open-source solutions to implement a feature:
+```bash
+iumbtems scout "Find high-throughput zero-dependency Raft consensus implementations in Rust or Go"
+```
+Or via npx:
+```bash
+npx @heretek-ai/epistemic-swarm scout "Scout vector database indexing algorithms with MIT or Apache-2.0 license"
+```
+Or directly with the python runner:
+```bash
+python3 runner/research_swarm.py --mode scout --objective "Explore clean-room alternatives to AGPL licensed search engines"
+```
+
+## 2. Dialectic Evaluation Workflow
+
+1. **Discovery (Alpha)**
+   - Explores GitHub, GitLab, crates.io, PyPI, npm, and Go packages.
+   - Compares star velocity, release frequency, benchmark throughput, and API design.
+   - Automatically caches repository documentation into `.research/sources/<sha256>.md`.
+
+2. **Adversarial Red-Teaming (Beta)**
+   - **License Contamination**: Flags AGPL/GPL requirements that could compromise proprietary or permissive codebases.
+   - **Maintenance Health**: Detects abandonware, stagnant commit logs, unresponsive PR queues, and solo maintainer risks.
+   - **Dependency Weight**: Audits transitive dependency explosion and bundle size.
+   - **Security Surface**: Scans for known CVEs and malicious package takeover vulnerabilities.
+
+3. **Synthesis & Clean-Room Blueprints**
+   - Synthesizes findings into `.research/oss_scout_report.md` and `.research/oss_scout_dossier.json`.
+   - Produces a **Clean-Room Blueprint**: an algorithmic breakdown allowing in-tree implementation of the core feature without licensing entanglement.
+
+## 3. Supported Package Ecosystems
+- GitHub & GitLab Repositories
+- Rust (crates.io)
+- Python (PyPI)
+- TypeScript / Node.js (npm)
+- Go Modules
+- C / C++ header-only libraries

package/skills/research_cache/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: research-cache
+description: Content-addressed document caching and quote verification skill. Hashes retrieved web pages and academic papers to SHA-256 for mathematical auditability.
+---
+
+# Content-Addressed Research Cache & Verification
+
+To maintain epistemic integrity, every document fetched from the web, arXiv, or technical docs must be cached locally with a content-addressed SHA-256 fingerprint before its claims can be cited.
+
+## 1. CACHING A SOURCE
+When you fetch or scrape a URL:
+```bash
+python3 skills/research-cache/hasher.py cache \
+  --url "https://arxiv.org/abs/2407.21783" \
+  --title "Llama 3 Herd of Models" \
+  --content "$(cat fetched_paper.md)"
+```
+This prints the content hash:
+```
+[CACHED] 3f8a9e21... -> .research/sources/3f8a9e21....md
+```
+
+## 2. CITING WITH HASHES
+In your dossiers and markdown reports, cite the claim using the hash:
+`[VERIFIED: 3f8a9e21]`
+
+Ensure that any `verbatim_quote` you provide is an exact substring from the cached markdown document.
+
+## 3. AUDITING A QUOTE
+The Epistemic Auditor verifies claims using:
+```bash
+python3 skills/research-cache/hasher.py verify \
+  --hash "3f8a9e21..." \
+  --quote "Our FPGA pipeline executes the Poseidon round constraints in 184ms"
+```
+If the quote does not match, the claim is rejected and flagged as unverified.

package/skills/research_cache/hasher.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""
+Content-Addressed Research Cache & Verbatim Quote Verification Engine.
+Handles SHA-256 document hashing, metadata indexing, and substring auditing.
+"""
+
+import os
+import sys
+import json
+import hashlib
+import re
+import argparse
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, Any, Optional, Tuple
+
+class SourceHasher:
+    def __init__(self, base_dir: Optional[Path] = None):
+        self.base_dir = base_dir or Path(".research")
+        self.sources_dir = self.base_dir / "sources"
+        self.sources_dir.mkdir(parents=True, exist_ok=True)
+
+    @staticmethod
+    def compute_sha256(content: str) -> str:
+        """Compute standard hex SHA-256 hash of normalized UTF-8 string."""
+        normalized = content.strip().encode("utf-8")
+        return hashlib.sha256(normalized).hexdigest()
+
+    def store_source(self, url: str, content: str, title: Optional[str] = None, 
+                     tier: str = "WEB_DOCUMENT", metadata: Optional[Dict[str, Any]] = None) -> str:
+        """Store content and metadata content-addressed by SHA-256."""
+        content_hash = self.compute_sha256(content)
+        md_path = self.sources_dir / f"{content_hash}.md"
+        json_path = self.sources_dir / f"{content_hash}.json"
+
+        # Write clean markdown
+        with open(md_path, "w", encoding="utf-8") as f:
+            f.write(content)
+
+        # Write metadata
+        meta = {
+            "hash": content_hash,
+            "url": url,
+            "title": title or "Untitled Source",
+            "tier": tier,
+            "cached_at": datetime.now(timezone.utc).isoformat(),
+            "byte_size": len(content.encode("utf-8")),
+            "char_count": len(content),
+            "custom_metadata": metadata or {}
+        }
+        with open(json_path, "w", encoding="utf-8") as f:
+            json.dump(meta, f, indent=2)
+
+        return content_hash
+
+    def get_source_content(self, content_hash: str) -> Optional[str]:
+        """Retrieve stored markdown content by full or prefix hash."""
+        target_file = self._resolve_hash_file(content_hash, ".md")
+        if target_file and target_file.exists():
+            with open(target_file, "r", encoding="utf-8") as f:
+                return f.read()
+        return None
+
+    def get_source_metadata(self, content_hash: str) -> Optional[Dict[str, Any]]:
+        """Retrieve stored metadata by full or prefix hash."""
+        target_file = self._resolve_hash_file(content_hash, ".json")
+        if target_file and target_file.exists():
+            with open(target_file, "r", encoding="utf-8") as f:
+                return json.load(f)
+        return None
+
+    def _resolve_hash_file(self, hash_prefix: str, extension: str) -> Optional[Path]:
+        """Resolves exact or prefix hash to disk path."""
+        exact_path = self.sources_dir / f"{hash_prefix}{extension}"
+        if exact_path.exists():
+            return exact_path
+
+        # If prefix match
+        matches = list(self.sources_dir.glob(f"{hash_prefix}*{extension}"))
+        if len(matches) == 1:
+            return matches[0]
+        return None
+
+    @staticmethod
+    def normalize_text_for_search(text: str) -> str:
+        """Collapse whitespace and normalize typography for substring matching."""
+        # Replace smart quotes and dashes
+        text = text.replace("“", '"').replace("”", '"').replace("‘", "'").replace("’", "'")
+        text = text.replace("—", "-").replace("–", "-")
+        # Collapse all whitespace to single spaces
+        return re.sub(r"\s+", " ", text).strip().lower()
+
+    def verify_quote(self, content_hash: str, quote: str) -> Tuple[bool, float, Optional[str]]:
+        """
+        Verifies whether quote exists in cached document.
+        Returns: (is_verified, confidence_score, context_match)
+        """
+        source_text = self.get_source_content(content_hash)
+        if not source_text:
+            return False, 0.0, f"Source hash '{content_hash}' not found in cache."
+
+        # 1. Exact match test
+        if quote.strip() in source_text:
+            return True, 1.0, "Exact substring match found."
+
+        # 2. Normalized whitespace match test
+        norm_source = self.normalize_text_for_search(source_text)
+        norm_quote = self.normalize_text_for_search(quote)
+        if norm_quote in norm_source:
+            return True, 0.98, "Normalized whitespace match found."
+
+        # 3. Sliding window token overlap test
+        quote_words = norm_quote.split()
+        if len(quote_words) < 4:
+            return False, 0.0, "Quote too short and not found verbatim."
+
+        window_size = len(quote_words)
+        source_words = norm_source.split()
+        best_score = 0.0
+
+        for i in range(max(1, len(source_words) - window_size + 1)):
+            window = source_words[i:i + window_size]
+            matches = sum(1 for w1, w2 in zip(quote_words, window) if w1 == w2)
+            score = matches / window_size
+            if score > best_score:
+                best_score = score
+                if best_score >= 0.90:
+                    break
+
+        if best_score >= 0.88:
+            return True, best_score, f"High-confidence fuzzy match ({best_score:.2f})."
+
+        return False, best_score, f"Verification failed. Highest word overlap: {best_score:.2f}."
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Epistemic Swarm Content Hasher & Quote Verifier")
+    subparsers = parser.add_subparsers(dest="command")
+
+    # Cache command
+    cache_parser = subparsers.add_parser("cache", help="Cache a document")
+    cache_parser.add_argument("--url", required=True, help="Original URL")
+    cache_parser.add_argument("--title", default="Untitled", help="Document Title")
+    cache_parser.add_argument("--tier", default="WEB_DOCUMENT", help="Source tier")
+    cache_parser.add_argument("--content", help="Raw text content (or read from stdin)")
+    cache_parser.add_argument("--dir", default=".research", help="Base .research directory")
+
+    # Verify command
+    verify_parser = subparsers.add_parser("verify", help="Verify a verbatim quote")
+    verify_parser.add_argument("--hash", required=True, help="Document SHA-256 hash")
+    verify_parser.add_argument("--quote", required=True, help="Verbatim quote to check")
+    verify_parser.add_argument("--dir", default=".research", help="Base .research directory")
+
+    # List command
+    list_parser = subparsers.add_parser("list", help="List cached sources")
+    list_parser.add_argument("--dir", default=".research", help="Base .research directory")
+
+    args = parser.parse_args()
+    hasher = SourceHasher(base_dir=Path(args.dir if hasattr(args, "dir") else ".research"))
+
+    if args.command == "cache":
+        content = args.content
+        if not content:
+            if not sys.stdin.isatty():
+                content = sys.stdin.read()
+            else:
+                print("Error: No content provided via --content or stdin.", file=sys.stderr)
+                sys.exit(1)
+        h = hasher.store_source(url=args.url, content=content, title=args.title, tier=args.tier)
+        print(f"[CACHED] {h} -> {args.title} ({args.url})")
+
+    elif args.command == "verify":
+        verified, conf, msg = hasher.verify_quote(content_hash=args.hash, quote=args.quote)
+        result = {
+            "hash": args.hash,
+            "verified": verified,
+            "confidence": conf,
+            "message": msg
+        }
+        print(json.dumps(result, indent=2))
+        sys.exit(0 if verified else 1)
+
+    elif args.command == "list":
+        sources = list(hasher.sources_dir.glob("*.json"))
+        print(f"Total Cached Sources: {len(sources)}")
+        for p in sources:
+            with open(p, "r", encoding="utf-8") as f:
+                d = json.load(f)
+                print(f"- [{d['hash'][:10]}...] {d['title']} ({d['url']})")
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

package/skills/swarm_config/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: swarm-config
+description: Dynamic configuration and settings skill for the Epistemic Swarm research harness. Manage search engines, research depth, dialectic iterations, operating modes (research, audit, scout), and license filters.
+---
+
+# Epistemic Swarm Configuration & Parameter Tuning
+
+Use this skill to inspect, tune, and persist research parameters into `.research/config.json`.
+Settings are automatically loaded by the Swarm Runner, Epistemic Auditor, and CLI.
+
+## 1. Interactive Configuration
+
+To launch the interactive configuration prompt:
+```bash
+python3 skills/swarm_config/configure.py --interactive
+```
+
+This guides you through selecting:
+1. **Primary Search Engine**:
+   - `duckduckgo` (Default, zero API key required, completely private)
+   - `brave` (Brave Search API for high-precision SERP results)
+   - `firecrawl` (Deep web scraping & JavaScript rendering)
+   - `searxng` (Self-hosted privacy metasearch aggregator)
+2. **Research Depth & Dialectic Iterations**:
+   - `1` (Rapid brief, minimal token usage)
+   - `2` (Standard thesis vs. antithesis dialectic - recommended)
+   - `3` (Deep multi-pass verification)
+   - `4` (Exhaustive multi-scope investigation)
+3. **Operating Mode**:
+   - `research` (Empirical literature & web synthesis)
+   - `audit` (Deep codebase architecture, security, and vulnerability red-teaming)
+   - `scout` (Open-source software discovery & clean-room harvesting)
+   - `hybrid` (Combined codebase audit + web research)
+
+## 2. Direct CLI Configuration
+
+Inspect the current active configuration:
+```bash
+python3 skills/swarm_config/configure.py --show
+```
+or via CLI:
+```bash
+iumbtems config
+```
+
+Update parameters directly via flags:
+```bash
+# Set search engine to duckduckgo and depth to 3
+python3 skills/swarm_config/configure.py --engine duckduckgo --depth 3
+
+# Set operating mode to codebase audit
+python3 skills/swarm_config/configure.py --mode audit
+
+# Set divergence threshold
+python3 skills/swarm_config/configure.py --divergence 0.8
+```
+
+## 3. Configuration Schema (`.research/config.json`)
+
+The active project configuration is persisted at `.research/config.json`:
+```json
+{
+  "search_engine": "duckduckgo",
+  "max_iterations": 2,
+  "divergence_threshold": 0.75,
+  "mode": "research",
+  "cache_raw_markdown": true,
+  "license_whitelist": ["MIT", "Apache-2.0", "BSD-3-Clause", "ISC"],
+  "output_dir": ".research"
+}
+```
+All swarm agents read this file at initialization time.

package/skills/swarm_config/__init__.py

@@ -0,0 +1,4 @@
+"""Epistemic Swarm configuration package."""
+from .configure import load_config, save_config, DEFAULT_CONFIG
+
+__all__ = ["load_config", "save_config", "DEFAULT_CONFIG"]