Graphify

Graphify is useful as a generated repo graph for codebase orientation and impact analysis. It should complement qmd, not replace it.

Routing Summary

Use Graphify when the task needs codebase topology: path questions, node explanations, affected-node/blast-radius checks, PR risk assessment, or repo onboarding where raw file search would waste context. Use QMD - Local Wiki Search Engine first when the question is about Kevin's compiled wiki, decisions, tools, concepts, people, or personal markdown brain.

What It Adds

Graphify scans a folder, builds a graph from code and document structure, and exposes commands such as query, path, explain, affected, save-result, and reflect. Its value is the graph-shaped retrieval step: instead of reading many files, the agent can ask for a focused subgraph and then inspect only the candidate files that matter.

The "71.5x fewer tokens" framing is best treated as a directional retrieval-economics claim, not a universal constant. The win depends on graph quality, query shape, repository size, and whether the question is structural enough for graph traversal.

Kevin-Wiki Boundary

qmd already provides the persistent, queryable map for this wiki's compiled markdown knowledge. Graphify does not replace that. In Kevin's stack:

qmd owns wiki-first answers, semantic search over compiled pages, and the qmd update && qmd embed maintenance loop.
Graphify owns codebase architecture maps, focused repo subgraphs, path/explain/affected commands, and per-repo answer reflection.
Durable lessons from Graphify should be promoted into wiki pages, skills, or project docs only when they become reusable knowledge.

Project Integration

Graphify should travel with projects through Agent-Docs Mesh, not through Graphify's own platform installers. agent-docs scaffold now emits a repo-graph auto-block into project AGENTS.md with the safe commands future agents should run.

For non-wiki repos, agents build and query from ~/Documents/GitHub/kevin-wiki:

PROJECT_ROOT="$(pwd)" && cd ~/Documents/GitHub/kevin-wiki && npm run graphify:sidecar -- build "$PROJECT_ROOT" --run outputs/graphify/<repo> --no-viz
cd ~/Documents/GitHub/kevin-wiki && npm run graphify:sidecar -- query "what should I inspect first?" --run outputs/graphify/<repo>

This keeps graphify-out/ out of product repos by default while still giving agents a persistent, queryable repo map.

Safe Invocation

Use the local sidecar wrapper:

npm run graphify:sidecar -- build .
npm run graphify:sidecar -- query "what connects auth to billing?"
npm run graphify:sidecar -- path "Auth" "Database"
npm run graphify:sidecar -- explain "RateLimiter"
npm run graphify:sidecar -- affected "BillingService" --depth 2
npm run graphify:sidecar -- reflect

The wrapper writes under outputs/graphify/<repo>/graphify-out/, disables Graphify query logging, and refuses installer/hook routes. Use --run DIR when building graphs for non-default targets.

Do Not Use For

Replacing qmd as the wiki source of truth.
Installing Graphify's Codex/Cursor/Claude hooks into this repo.
Writing graphify-out/ into a target repo by default.
Bulk personal-doc, transcript, or private-note extraction when qmd already answers locally.
Treating generated graph labels or inferred edges as durable truth without source-file verification.

Current Snapshot

Local source inspection on 2026-07-02 saw package version 0.9.4 and a pipeline centered on detect -> extract -> build_graph -> cluster -> analyze -> report -> export. The repository's installer can write platform skills, hooks, and agent instructions; Kevin's implementation intentionally uses only the sidecar query/build/reflect surface.

Timeline

2026-07-03 | Wired Graphify into per-project agent docs: agent-docs scaffold emits a repo-graph auto-block, while generated graph artifacts stay in kevin-wiki/outputs/graphify/<repo>/. Source: User request, 2026-07-03
2026-07-02 | Added Graphify as a safe sidecar route after evaluating overlap with qmd. Decision: keep qmd as the wiki retrieval layer and use Graphify for repo architecture graphs, path/explain/affected queries, and graph answer reflection. Source: User request, 2026-07-02; local source inspection

Source: User request, 2026-07-03