ADR-007 — OKF graph visualizer: single-file, client-side, in tools/

Status

accepted — 2026-07-03 (decided by: taranas, TPL)

Context

We want an Obsidian-quality interactive graph view of an OKF bundle (this vault, and eventually any Knowledge-OS repo or the client’s future vanos-brain vault) that can be handed to anyone — CEO, department heads, TPL colleagues — with zero setup. Constraints: the vault content is data_sensitivity: high, so nothing may be uploaded anywhere; viewers cannot be assumed to have Obsidian, Node, or any tooling; and this repo documents Prime Products, it does not run infrastructure (ADR-001, amended by ADR-005 for site/).

Options considered:

1. Obsidian’s own graph view — requires Obsidian + a vault checkout; not shareable as an artifact; per-viewer setup.
2. A page in the Mission Control Astro site (site/) — couples the visualizer to the site build and to publish: mission-control opt-in docs only; useless for other bundles and for offline hand-off.
3. A single self-contained HTML file — chosen. One file that parses any dropped OKF bundle (Markdown + YAML frontmatter, wikilinks and relative links) entirely in the browser and renders a force-directed graph. No dependencies, no build, no network.

Decision

1. The visualizer lives at tools/okf-graph/okf-graph.html — one self-contained file: minimal YAML-subset parser, wikilink/markdown-link resolver (Obsidian-style: exact path, then unique basename, shortest path wins), Barnes-Hut force simulation, canvas renderer, search, filters, inspector.
2. Everything is client-side. A strict CSP <meta> (default-src 'none') hard-blocks all network access as a verifiable guarantee that no data leaves the page. Works from file://.
3. Snapshots: the file can export a copy of itself with the parsed graph embedded (frontmatter + link structure only — note bodies are never embedded), so a one-file interactive snapshot can be shared. Snapshots of this vault inherit its confidentiality: treat them as data_sensitivity: high and share only within the project team.
4. tools/ becomes the second narrowly-scoped code exception after site/ (ADR-005): self-contained utilities for viewing/checking the vault — code conventions apply there, never knowledge content. The bundled demo dataset is synthetic (fictional “Aurora Robotics”), holding no Prime Products data.
5. Colors follow the TPL dataviz method: validated 8-slot categorical palette (light and dark selected separately), slots assigned to groups in fixed frequency order, 9th+ group folds into a muted “other” — with the legend + on-canvas direct labels as the relief encoding.

Consequences

• Anyone can view the vault as a graph by opening one HTML file and dropping the repo folder on it — no install, no upload; README/CLAUDE.md gain the tools/ exception.
• The parser implements a YAML subset (scalars, inline/block lists, one nested map level) — exotic frontmatter would parse partially; acceptable for OKF-conformant docs, verified against all 90 files of this vault (531 links resolved, 0 false ghosts).
• The graph reflects body links + frontmatter only; it does not execute Dataview or resolve cross-vault federation links (they fall back to basename matching or show as unresolved ghosts).
• If Mission Control later wants a graph page, site/ can embed or link this file rather than reimplementing (kept decoupled on purpose).