The 3D nebula that maps the Brain Vault is about 1,700 stars and 7,000 lines drawn between them in WebGL. It's beautiful when it works. When I opened it in September 2026, I got a black screen.
The plugin — I call it Cosmos — was built in the same coding session as five other features: a health check, a citation validator, two import playbooks, and an upgrade to the weekly review. All six features passed 31 tests, including a full integration run against the real vault. The tests saw the graph. I didn't.
Scene fog was washing the additive-blend sprites to black. No assertion caught it because every test validated the graph data and the rendering logic separately. Nobody asked: does a human looking at the screen see what the data says should be there?
This piece is about what that screen should have shown, why the standard graph view turns into a hairball, and what a handful of PageRank scores and a layout seed can do about it.
The problem with treating every link as equal
The Brain Vault holds 1,765 documents — 869 synthesized notes plus 822 raw imports — with 7,075 links in the synthesized layer, a median of 5 per document. If you render all of those as a force-directed graph with equal edge weights, you get a dense ball where nothing stands out and the nodes nearest the camera block everything behind them.
That's the graph view most tools give you by default. It shows the structure exists. It doesn't show what matters.
The Cosmos plugin takes a different approach. It renders a sparse version of the full analytical graph: only the top-K highest-PageRank edges for each node, with the ranks themselves used as masses. Domains become stars, the 50 concept pillars become planets, and evidence notes become moons. The layout is seeded so the graph opens to the same view every time, not a different tangle.
The distinction the plugin makes is this: the full graph is for analysis — agent playbooks walk it, the weekly review queries it, and health checks validate it. The visualization is for navigation. A human needs to see the structure, not count every edge.
How PageRank turns links into mass
PageRank is a standard-library algorithm. The Python script that builds the vault's link graph ranks only the synthesized layer — the 869 notes and 50 pillars, never the raw imports — and writes the scores into each document's frontmatter as a number between zero and one.
A concept pillar with 80 inbound links from high-rank documents gets a higher score than a one-off note with two backlinks. The score becomes the node's mass in the visualization, so pillars pull nearby notes toward them and sit at stable positions in the layout.
The same scores drive the sparse-edge filter. For each node, the plugin keeps only the top 12 outbound edges ranked by the target's PageRank. A note that links to a pillar and eleven minor references will show the pillar connection; the weak edges disappear from the view but remain in the data.
This is not a lossy reduction. The full graph still exists. The visualization shows the paths an agent or a human would actually follow.
The nebula that never rendered
The black-screen bug happened because Cosmos uses additive blending for the star sprites, and the scene fog was set to black. Additive blend means each pixel's color is added to what's behind it, so a bright dot in fog looks dimmer the farther away it is. When the fog color is black — RGB(0,0,0) — and you're adding to zero, distant stars wash out to nothing.
The fix was a one-line change: fog color to a dark blue that preserves the glow. But the defect survived 31 tests because no test rendered the scene and checked what a human would see. The integration test validated that the plugin could read the vault's frontmatter, build the graph data structure, and initialize the WebGL context. It did not open a window and ask: is there anything visible?
I found it by looking. That's the part no gate covered.
What broke and how I fixed it
The feedback loop that day ran through five fix rounds, and the record drifted because three of those rounds happened in chat and were never written down. The feedback document's round numbers don't line up with the coding session's commit log. That's a small defect in the process: the written record should match what actually happened, and it doesn't.
The larger lesson is that the test suite can validate logic, data flow, and API contracts, and still miss the most obvious question: does the output look right to the person using it?
A test that renders a small test graph to a headless canvas, samples a few pixel values, and asserts that stars are visible would have caught this in CI. I haven't written it yet. The plugin is built, not shipped — it works, I use it, and that one feedback round is still open.
Why this matters for knowledge graphs
Most people treat a graph view as a diagnostic: proof that the links exist. I built Cosmos to make the vault navigable. The distinction is that a diagnostic can be messy, but a navigation tool has to show you where to go.
The Brain Vault is structured so an agent can act on real context — 17 playbooks define named routines, frontmatter holds the agent's index, and 96% of documents carry structured metadata. The graph is the map of that structure. An agent reads the full graph; a human needs the version that highlights the paths that matter.
Sparse top-K edges and PageRank as mass turn the hairball into a map. The layout seed keeps it stable across sessions. And the bug that shipped with 31 passing tests is a reminder that the gates I built cover what I thought to check, not everything that can go wrong.
The fix was one line. The gap it exposed — that a test suite can be thorough and still miss the thing a human sees in three seconds — is the kind of thing I write down so I remember to test for it next time.