# Entity Relationship Explorer

- **Command:** `lore graph <entity-type> <iid>`
- **Confidence:** 80%
- **Tier:** 3
- **Status:** proposed
- **Effort:** medium — BFS traversal (similar to timeline expand), output formatting

## What

Given an issue or MR, traverse `entity_references` and display all connected
entities with relationship types and depths. Output as tree, JSON, or Mermaid diagram.

## Why

The entity_references graph is already built (Gate 2) but has no dedicated
exploration command. Timeline shows events over time; this shows the relationship
structure. "What's connected to this issue?" is a different question from "what
happened to this issue?"

## Data Required

All exists today:
- `entity_references` (source/target entity, reference_type)
- `issues` / `merge_requests` (for entity context)
- Timeline expand stage already implements BFS over this graph

## Implementation Sketch

```
1. Resolve entity type + iid to local ID
2. BFS over entity_references:
   - Follow source→target AND target→source (bidirectional)
   - Track depth (--depth flag, default 2)
   - Track reference_type for edge labels
3. Hydrate each discovered entity with title, state, URL
4. Format as tree / JSON / Mermaid
```

## Human Output (Tree)

```
#42 Login timeout bug (CLOSED)
  ├── closes ── !234 Refactor auth middleware (MERGED)
  │   ├── mentioned ── #38 Connection timeout in auth flow (CLOSED)
  │   └── mentioned ── #51 Token refresh improvements (OPEN)
  ├── related ── #45 Auth module documentation (OPEN)
  └── mentioned ── !228 Database migration (MERGED)
      └── closes ── #35 Schema version drift (CLOSED)
```

## Mermaid Output

```mermaid
graph LR
    I42["#42 Login timeout"] -->|closes| MR234["!234 Refactor auth"]
    MR234 -->|mentioned| I38["#38 Connection timeout"]
    MR234 -->|mentioned| I51["#51 Token refresh"]
    I42 -->|related| I45["#45 Auth docs"]
    I42 -->|mentioned| MR228["!228 DB migration"]
    MR228 -->|closes| I35["#35 Schema drift"]
```

## Downsides

- Overlaps somewhat with timeline (but different focus: structure vs chronology)
- High fan-out for popular entities (need depth + limit controls)
- Unresolved cross-project references appear as dead ends

## Extensions

- `lore graph --format dot` — GraphViz DOT output
- `lore graph --format mermaid` — Mermaid diagram
- `lore graph --include-discussions` — show discussion threads as nodes
- Interactive HTML visualization (future web UI)