Knowledge Graph (graphify)

Build a map of how this AIOS actually fits together — which code files and which wiki notes depend on, reference, and cluster with each other — so you can see the structure instead of guessing it. Powered by graphify (a knowledge-graph builder), scoped hard to what's safe to graph.

When to run

• The user asks to see how the repo / second brain hangs together ("map the codebase", "graph the repo").
• After meaningful structural change — new skills, tools, SOPs, or a /wiki loop that added entries — to refresh the picture.
• As a thinking aid before a refactor, an audit, or a /weekly review: what's load-bearing, what's orphaned, what's surprisingly connected.
• Before exploring with /graph-query (this builds/refreshes the graph it queries).

The output (always this shape)

graphify writes everything to graphify-out/ (git-ignored — a derived artifact, never committed):

## Knowledge graph — <date>
**Built from** — code (local AST) + committed wiki/. Excluded: raw/, .tmp/, .env, secrets.
**Artifacts** — graphify-out/graph.html (interactive) · graph.json · GRAPH_REPORT.md

**God Nodes** — the most-connected hubs (what everything leans on):
1. <node> — <why it's central, in a phrase>
2. … 3. …
**Surprising Connections** — edges you wouldn't expect (cross-domain links worth a look):
- <A> ↔ <B> — <what the link is>
**Suggested Questions** — what the graph invites you to ask next:
- <question> → run `/graph-query "<question>"`

Every edge carries graphify's honesty label — EXTRACTED (read directly), INFERRED (reasoned), or AMBIGUOUS — so claims about the graph cite their basis (cite-don't-invent).

Process

1. Ensure graphify is installed. Run python tools/graphify_setup.py check. If missing, offer to install (uv tool install graphifyy, fallback pipx install graphifyy / pip install graphifyy, then graphify install --platform claude). No account or signup is needed. Gate: don't proceed until graphify --version resolves.
2. Set the build scope — code + committed wiki/ ONLY. This is the hard line:
   • Include: source code (Python in tools/, etc.) and the committed wiki/.
   • EXCLUDE always: raw/ (may hold raw PHI/PII/financials before de-identification), .tmp/, .env, graphify-out/, and any sensitive/secret path. Never point graphify's document extraction at raw/.
   • Why this is safe: code is parsed locally by tree-sitter AST (no LLM, nothing leaves the machine); document extraction is limited to wiki/, which is already de-identified and non-confidential per the wiki admission policy. graphify also auto-skips sensitive files during detection — but scope, not that fallback, is your guardrail.
3. Build the graph.
   • Full build (code + wiki): the heavy document pass runs through graphify's own pipeline using the host IDE session — invoke /graphify . (graphify's global skill), having confirmed scope. Non-code text in wiki/ is extracted by this session; graphify does not call any third party or read ANTHROPIC_API_KEY in-IDE.
   • Code-only refresh (no LLM, fast): run graphify update <path> — re-extracts the code AST deterministically, no model call. Prefer this when only code changed.
   • Gate: confirm graphify-out/graph.json and GRAPH_REPORT.md were written before reporting.
4. Surface the highlights. Read graphify-out/GRAPH_REPORT.md and summarize into the output shape above — God Nodes, Surprising Connections, Suggested Questions — keeping the EXTRACTED/INFERRED/AMBIGUOUS labels. Point the user at graphify-out/graph.html for the interactive view.
5. Offer the next move. Propose /graph-query "<question>" to explore (shortest paths, neighbors, communities), and — if the user wants it standing — graphify hook install for auto-rebuild on commit (a Cadence touch) or --watch for continuous rebuild while working.

Autonomy

L2 — drafts/refreshes the graph; the human reads it. Building is reversible and lands only in git-ignored graphify-out/, so it's safe to run on request. A code-only graphify update (deterministic, no LLM, no document pass) can run at L3 — e.g. via the commit hook — once trusted. Never commit graphify-out/; never widen scope beyond code + wiki/ without explicit approval.

Guardrails (from CLAUDE.md)

• Never extract raw/ (or .env, .tmp/, secrets) — raw/ can hold pre-de-identified PHI/PII/financials. Document extraction is limited to the committed, de-identified wiki/. (Guardrails #1, #2, #7)
• graphify-out/ is git-ignored — a derived artifact. No secrets, confidential figures, or sensitive data enter git via the graph.
• Cite, don't invent. Carry graphify's honesty audit trail (EXTRACTED / INFERRED / AMBIGUOUS) into any claim about the graph. (Guardrail #6)
• Code AST is parsed locally; the wiki document pass uses this host session only — no third-party call, no ANTHROPIC_API_KEY read.