# Clew

The thread through a brownfield maze. A **hop** is a node on that thread (`docs/hops.md`).

<p align="center">
  <img src="docs/assets/clew.jpg" width="220" alt="A clew — a ball of thread">
</p>

<p align="center">
  <a href="https://jeunessegamesee.github.io/clew/"><strong>Website</strong></a>
  ·
  <a href="docs/story.html">Story</a>
  ·
  <a href="SPEC.md">SPEC</a>
  ·
  <a href="GETTING_STARTED.md">Getting started</a>
  ·
  MIT
</p>

Brownfield services already work. Coding agents still pay to rediscover the same multi-service flow every session. Clew keeps the four graphs you already have — code, catalog, loadout, traces — and joins them onto a path you can walk.

```text
Input → Branches → Output
measure → one P0 → capture → measure    until reflected
```

```bash
go install github.com/jeunessegamesee/clew/cmd/clew@v0.1.1
```

No Scale license, no Neo4j, no OpenSearch.

## Any brownfield, three commands

```bash
clew init --root /path/to/repo     # .clew.yaml + CLEW.md
clew stub --root /path/to/repo     # IN+else for every gRPC / GraphQL / OpenAPI port
clew score --root /path/to/repo    # P0 = missing IN; P1 = uncaptured branches
clew loadout --root /path/to/repo --in /package.Service/Method
```

Stubs let you *refer* to every inbound port. Trees with no `when` stay P1 uncaptured. Deepen with `clew loop` — do not invent branches.

## Build from source

```bash
go test ./...
go build -o clew ./cmd/clew
./clew score --root examples/shop --fail-p0
./clew loadout --root examples/shop --use-case place-order --payload '{"paymentMethod":"CARD"}'
./clew loop --root testdata/incomplete-shop
```

```bash
./clew score --root examples/shop --by-service
./clew score --root examples/shop --fail-p1
./clew watch --root examples/shop --traces traces/live.jsonl --follow
./clew watch --root examples/shop --listen 127.0.0.1:4318
./clew mcp
```

`clew mcp` is a stdio MCP server (`loadout`, `who_consumes`, `who_calls`, `next_p0`, `drift`, `score`). Each tool has its own input schema.

## Adapt file

`.clew.yaml` is how a stranger repo becomes a map:

```yaml
roots:
  - .
  - ../other-repo
services:
  checkoutservice: src/checkoutservice   # OTel service.name → hops folder
traces:
  - traces/*.json
```

**Generic doors** (no per-framework parser): OpenAPI / proto / GraphQL, OTLP (`clew watch`), or `clew ingest --file doors.json`. Optional `http: [auto]` guesses Actix/Spring/… and is not how a new stack is added.

## Language

Clew is Go. CBM stays the code graph. We join HTTP/ASYNC/CROSS, OpenAPI/AsyncAPI, and OTLP — we do not rebuild an indexer.

## Map format

See [SPEC.md](SPEC.md). Per service: `docs/hops.md`. Coverage: `clew score --fail-p0`. After executable: `--fail-p1` freezes uncaptured stubs.