graphify

What this skill does

# /graphify

Turn any folder of files into a navigable knowledge graph with community detection, an honest audit trail, and three outputs: interactive HTML, GraphRAG-ready JSON, and a plain-language GRAPH_REPORT.md.

## Usage

```
/graphify                                             # full pipeline on current directory
/graphify <path>                                      # full pipeline on specific path
/graphify <path> --mode deep                          # thorough extraction, richer INFERRED edges
/graphify <path> --update                             # incremental - re-extract only new/changed files
/graphify <path> --directed                           # build directed graph (preserves edge direction)
/graphify <path> --whisper-model medium               # use a larger Whisper model for transcription
/graphify <path> --cluster-only                       # rerun clustering on existing graph
/graphify <path> --no-viz                             # skip visualization, just report + JSON
/graphify <path> --html                               # (HTML is generated by default - no-op)
/graphify <path> --svg                                # also export graph.svg
/graphify <path> --graphml                            # export graph.graphml (Gephi, yEd)
/graphify <path> --neo4j                              # generate graphify-out/cypher.txt for Neo4j
/graphify <path> --neo4j-push bolt://localhost:7687   # push directly to Neo4j
/graphify <path> --mcp                                # start MCP stdio server for agent access
/graphify <path> --watch                              # watch folder, auto-rebuild on code changes
/graphify <path> --wiki                               # build agent-crawlable wiki
/graphify <path> --obsidian --obsidian-dir ~/vaults/my-project  # write Obsidian vault
/graphify add <url>                                   # fetch URL, save to ./raw, update graph
/graphify add <url> --author "Name"                   # tag who wrote it
/graphify add <url> --contributor "Name"              # tag who added it
/graphify query "<question>"                          # BFS traversal - broad context
/graphify query "<question>" --dfs                    # DFS - trace a specific path
/graphify query "<question>" --budget 1500            # cap answer at N tokens
/graphify path "AuthModule" "Database"                # shortest path between two concepts
/graphify explain "SwinTransformer"                   # plain-language explanation of a node
```

## What graphify is for

graphify is built around Andrej Karpathy's /raw folder workflow: drop anything into a folder - papers, tweets, screenshots, code, notes - and get a structured knowledge graph that shows you what you didn't know was connected.

Three things it does that Claude alone cannot:
1. **Persistent graph** - relationships are stored in `graphify-out/graph.json` and survive across sessions. Ask questions weeks later without re-reading everything.
2. **Honest audit trail** - every edge is tagged EXTRACTED, INFERRED, or AMBIGUOUS. You know what was found vs invented.
3. **Cross-document surprise** - community detection finds connections between concepts in different files that you would never think to ask about directly.

Use it for:
- A codebase you're new to (understand architecture before touching anything)
- A reading list (papers + tweets + notes - one navigable graph)
- A research corpus (citation graph + concept graph in one)
- Your personal /raw folder (drop everything in, let it grow, query it)

## What You Must Do When Invoked

If no path was given, use `.` (current directory). Do not ask the user for a path.

Follow these steps in order. Do not skip steps.

### Step 1 - Ensure graphify is installed

```bash
# Detect the correct Python interpreter (handles uv tool, pipx, venv, system installs)
PYTHON=""
GRAPHIFY_BIN=$(which graphify 2>/dev/null)
# 1. uv tool installs
if [ -z "$PYTHON" ] && command -v uv >/dev/null 2>&1; then
    _UV_PY=$(uv tool run graphifyy python -c "import sys; print(sys.executable)" 2>/dev/null)
    if [ -n "$_UV_PY" ]; then PYTHON="$_UV_PY"; fi
fi
# 2. Read shebang from graphify binary (pipx and direct pip installs)
if [ -z "$PYTHON" ] && [ -n "$GRAPHIFY_BIN" ]; then
    _SHEBANG=$(head -1 "$GRAPHIFY_BIN" | tr -d '#!')
    case "$_SHEBANG" in
        *[!a-zA-Z0-9/_.-]*) ;;
        *) "$_SHEBANG" -c "import graphify" 2>/dev/null && PYTHON="$_SHEBANG" ;;
    esac
fi
# 3. Fall back to python3
if [ -z "$PYTHON" ]; then PYTHON="python3"; fi
"$PYTHON" -c "import graphify" 2>/dev/null || "$PYTHON" -m pip install graphifyy -q 2>/dev/null || "$PYTHON" -m pip install graphifyy -q --break-system-packages 2>&1 | tail -3
# Write interpreter path for all subsequent steps
mkdir -p graphify-out
"$PYTHON" -c "import sys; open('graphify-out/.graphify_python', 'w').write(sys.executable)"
```

If the import succeeds, print nothing and move straight to Step 2.

**In every subsequent bash block, replace `python3` with `$(cat graphify-out/.graphify_python)` to use the correct interpreter.**

### Steps 2-5 - Build pipeline

Read [references/pipeline-steps.md](references/pipeline-steps.md) for the full pipeline:
- **Step 2** - Detect files (corpus scan, size warnings)
- **Step 2.5** - Transcribe video/audio (Whisper, only if video detected)
- **Step 3** - Extract entities and relationships (Part A: AST for code, Part B: parallel semantic subagents for docs/papers/images, Part C: merge)
- **Step 4** - Build graph, cluster, analyze
- **Step 5** - Label communities with plain-language names

### Steps 6-9 and Subcommands

Read [references/subcommands.md](references/subcommands.md) for:
- **Step 6** - Generate HTML + Obsidian vault (opt-in)
- **Step 6b** - Wiki generation (--wiki flag)
- **Step 7** - Neo4j, SVG, GraphML, MCP exports
- **Step 8** - Token reduction benchmark
- **Step 9** - Cleanup and final report
- **Subcommands** - --update, --cluster-only, query, path, explain, add, --watch, hook, claude install

## Key Extraction Rules (always loaded)

These rules apply to every extraction regardless of which reference file you are reading:

### Confidence tagging
- **EXTRACTED**: relationship explicit in source (import, call, citation)
- **INFERRED**: reasonable inference (shared data structure, implied dependency)
- **AMBIGUOUS**: uncertain - flag for review, do not omit

### confidence_score (REQUIRED on every edge)
- EXTRACTED edges: always 1.0
- INFERRED edges: 0.8-0.9 (strong evidence), 0.6-0.7 (reasonable), 0.4-0.5 (weak)
- AMBIGUOUS edges: 0.1-0.3

### Node ID format
Lowercase, only `[a-z0-9_]`. Format: `{stem}_{entity}` where stem is filename without extension, entity is symbol name. Example: `src/auth/session.py` + `ValidateToken` -> `session_validatetoken`.

### Subagent rules
- **MUST use Agent tool** for semantic extraction - reading files one-by-one is forbidden
- Always use `subagent_type="general-purpose"` (NOT Explore - it cannot write to disk)
- Always use `model: "sonnet"` for extraction subagents

## Honesty Rules

- Never invent an edge. If unsure, use AMBIGUOUS.
- Never skip the corpus check warning.
- Always show token cost in the report.
- Never hide cohesion scores behind symbols - show the raw number.
- Never run HTML viz on a graph with more than 5,000 nodes without warning the user.