# Clew Engine: Distribution Specification

## Overview
The Clew Engine follows a **Local-First Distribution Model** — open source, Docker-packaged, MCP-native.

---

## Distribution Goals

### G1: Open Source Core
**License:** MIT or Apache 2.0

| Requirement | Rationale |
|---|---|
| Full source visibility | Developers won't trust a "Memory Layer" with their code unless auditable |
| No "open core" traps | Core functionality is complete without paid features |

---

### G2: One-Command Infrastructure
**Command:** `docker-compose up -d`

| Requirement | Acceptance Criteria |
|---|---|
| Single `docker-compose.yml` | Starts Neo4j, Qdrant, API |
| Zero external dependencies | No accounts, no signups, no API keys required |
| Cross-platform | Mac, Linux, Windows (WSL2) |

**Onboarding Flow:**
```bash
git clone https://github.com/matchdav/clew-engine.git
cd clew-engine
docker-compose up -d
# → Ready in < 2 minutes
```

---

### G3: MCP-First Interface
**Protocol:** Model Context Protocol (Stdio/HTTP)

| Requirement | Acceptance Criteria |
|---|---|
| Stdio transport | Works with Claude Code, Cursor, Windsurf |
| Two core tools | `search_codebase`, `navigate_context` |
| HTTP fallback | `localhost:8000/v1/search`, `/v1/graph/traverse` |

**IDE Integration:**
```json
{
  "clew": {
    "command": "./start_mcp.sh",
    "args": []
  }
}
```

---

### G4: CLI Management (Future)
**Package:** `clew-cli`

| Command | Function |
|---|---|
| `clew ingest <repo-url>` | Index a repository |
| `clew search <query>` | Vector search from terminal |
| `clew graph <file>` | Show relationships for a file |
| `clew status` | Indexed repos, node/edge counts |

---

### G5: Local-First, Zero-Cost
**Constraint:** No cloud dependency for core functionality.

| Component | Local Deployment |
|---|---|
| Neo4j | Community Edition (container) |
| Qdrant | OSS (container) |
| Embeddings | Ollama or hash fallback |
| Compute | User's machine |

---

## Success Metrics

| Metric | Target |
|---|---|
| Time to first query | < 5 minutes |
| Docker image size (API) | < 500MB |
| Cold start latency | < 3s |
| MCP response time | < 500ms (search) |

---

## Platform Overlap

The following features are **shared concerns** between Engine and Platform:

| Feature | Engine Scope | Platform Scope |
|---|---|---|
| MCP Server | Local Stdio | Hosted HTTP endpoint |
| Ingestion | Manual CLI trigger | GitHub webhook automation |
| Auth | None (localhost) | Clerk/OAuth |
| Billing | N/A | Stripe usage metering |
| DB Location | Local Docker | BYO DB or Managed |

**Boundary:** The Engine is self-contained. The Platform wraps the Engine with auth, billing, and multi-tenancy — but is not required.

---

## Non-Goals (V1)

- Kubernetes/Helm (Platform tier only)
- Windows native (Docker Desktop required)
- GUI dashboard (CLI and MCP only)
- Managed hosting (Platform tier)