---
name: vault-graph
description: Render the brain's knowledge graph and show it in chat BOTH ways at once — the Obsidian-style picture inline (every note a dot sized by its links, wikilinks as threads, folder-colored, force-laid-out on the near-black canvas) plus the live interactive pane (hover a node for its label + PEAK location + lit neighborhood, click to pin, drag/scroll to pan and zoom, ☰ folder legend). Wraps the engine's `graph_image` module, a headless port of the desktop app's 2D graph view (same scan as graph_get, same d3-force physics, same palette — plus a no-overlap pass, so no two notes ever render on top of each other). Use when the owner says "show me my brain", "show my graph", "graph my vault", "what does my brain look like", "render the knowledge graph", "interactive graph", "graph around <note>", "map my notes", or wants the picture for a deck, a post, or a progress note. Read-only against the notes (it writes only into the gitignored `.state/cache/`); NOT vault-health/vault-stats (those are numbers — this is the picture), NOT the desktop app's live Graph tab (offer it for extended exploring).
served: true
---

# Vault graph — the brain as a picture AND a live pane

The brain, as a picture: every note a dot sized by how linked it is (well-connected hubs in warm sand), every wikilink a faint thread, arranged by the same force model the desktop app and Obsidian run. The generator is deterministic — the same vault renders the same image — and caches its layout, so the first render simulates from scratch and later ones settle in seconds.

When this skill fires:

1. **Run the generator** from the vault root — one run emits everything (png + svg + html), into the gitignored machine-local cache (never committed):
   ```sh
   "${ALEXANDRIA_PYTHON:-python3}" -m alexandria_vault.engine.graph_image --vault . --json --format all --out .state/cache/vault-graph.html
   ```
   It prints one JSON line (output paths, note/link/component counts, top hubs, timings). The engine lives in the installed `alexandria-vault` package; `ALEXANDRIA_PYTHON` — the app venv's python — is the interpreter that has it. On a first render of a large vault the simulation can take a minute or two (progress prints to stderr); it warm-starts from `.state/cache/` on every later run, and `--relayout` re-rolls the composition. Ask before reaching for `--fast` — it trades a little layout quality for ~4x speed. Defaults are the house style: a hue per top-level folder / `Areas/<Area>`, 4K-class 4000x3000, path-anchored layout (the composition stays recognizable as the vault grows), and the no-overlap guarantee — after the physics settle, touching notes are eased apart (hubs hold their ground, leaves shift) so no two nodes overlap in any output; `--no-collide` keeps the raw physics placement.

2. **Show both, always — never just name a path.** Attach/send the PNG so the picture renders inline (the transcript keeps it), AND open `.state/cache/vault-graph.html` in a browser/preview tab, then front it. Files inside the vault preview LIVE in Claude Code's pane (hover, pin, zoom, ☰ all work), while a copy outside the session folder previews as a static snapshot — that placement is the whole trick, no server needed. Talking to a served brain from a chat client, `file_put` + `file_url` yields a link the client can render. Offer the desktop app's Graph tab when the owner wants to *explore* at length.

3. **Report the shape in one breath** alongside the picture, from the JSON: notes · links · components · orphans, and the two or three biggest hubs by degree. No note dump.

4. **Shape the render to the ask.** Reach for flags when the owner's words call for them:
   - *"graph around X" / one area or note* → `--focus "X" --hops 2` (accent on the note, its neighborhood lit, the fringe dimmed; focus runs skip the layout cache).
   - *names on the picture* → `--labels 24` labels the most-linked hubs (small caps, collision-culled).
   - *the classic monochrome look* → `--no-color-by-folder` (gray notes, warm-sand hubs); explicit `--group "People=#8fb573"` (repeatable) overrides a prefix's hue either way.
   - *look* → `--theme obsidian` (all-gray Obsidian look), `--theme light` (documents/decks), default `desktop`.
   - *the not-yet-created notes too* → `--include-unresolved` adds faded phantom nodes.
   - *print / wallpaper* → `--width 8000 --height 6000` (8K, expect a few minutes to draw) or `--width 3840 --height 2160` (UHD); the `.svg` landing beside the others covers vector needs.

5. **Never publish the html to a hosted surface without the owner's explicit ask** — the page embeds every note title, and that is vault egress, never a default.

6. **Keep or toss.** `.state/cache/` is the default home and needs no tending. Keeping a copy: write it to `Agent/Graphs/<date> Vault Graph.png`, commit it with explicit paths, and offer a daily-note line (`📷 [[<date> Vault Graph.png]]`).
