graph

# 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.