Status: Draft Date: 2026-05-27 Project: Glyph

​
Thesis

Glyph’s source graph should be visible. Humans and agents need a way to inspect the mesh of work contexts, snapshots, publications, source objects, content objects, claims, conflicts, hooks, remotes, and audit events without spelunking through SQLite tables by hand.

​
Goals

  • Provide a local visualizer for .glyph/ state.
  • Export machine-readable graph data.
  • Render a static HTML view that requires no hosted service.
  • Show relationships between work, source, publication, hooks, and concurrency state.
  • Keep private/local visibility explicit; the visualizer is a local diagnostic tool in v0.

​
Non-Goals

  • Building a hosted dashboard.
  • Real-time collaborative graph streaming.
  • Replacing CLI status/diff commands.
  • Exposing private .glyph data publicly.

​
Graph Model

The visualizer exports nodes and edges. Initial node types:
  • store
  • realm
  • work
  • snapshot
  • publication
  • source
  • content
  • claim
  • conflict
  • hook_run
  • remote
  • mount
Initial edge types:
  • contains
  • belongs_to
  • based_on
  • points_to
  • captured
  • published
  • claimed_by
  • conflicts_with
  • ran_hook
  • syncs_to
  • mounted_at
Nodes should include stable IDs, labels, type, and detail maps. Edges should include source, target, type, and optional detail maps.

​
Timeline Model

The visualizer also exports ordered events. Initial event sources:
  • append-only audit JSONL events
  • work context creation and updates
  • snapshot creation
  • publication records
  • hook runs
  • remote sync records
Events should include stable IDs, event type, label, timestamp, actor, detail maps, and related node IDs when they can be inferred. This lets the UI show a chronological history while still connecting each operation back to the mesh. The timeline is not a replacement for the graph. It is a way to answer “what happened when?” while the graph answers “what is connected to what?”

​
CLI Surface

Prototype command: 
glyph viz export --out .glyph/visualizer --json
The command writes: 
.glyph/visualizer/
  index.html
  graph.json
graph.json is the canonical export artifact. index.html is a local viewer over that artifact.

​
UI Requirements

The first visualizer should be simple but useful:
  • Filter by node type.
  • Search by ID, label, path, actor, or realm.
  • Show graph nodes and edges.
  • Show selected node details as JSON.
  • Show an event timeline ordered by timestamp.
  • Let timeline events highlight related graph nodes.
  • Show graph summary counts.
The v0 renderer can use plain HTML, CSS, and browser JavaScript. It should not require a server or external network dependencies.

​
Security Requirements

Visualizer exports may reveal private source paths, actor identities, hooks, and audit metadata. Default behavior:
  • Export from local .glyph only.
  • Write output under a local path.
  • Do not publish or sync visualizer output unless explicitly requested.
  • Treat generated graph.json as sensitive unless generated from a public realm projection in a future scoped export mode.

​
Prototype Defaults

  • Static export only.
  • All local store metadata visible in the generated graph.
  • No external JavaScript dependencies.
  • No live updates.
  • Graph data includes metadata, not raw file contents.

​
Success Criteria

This spec is successful if a prototype can:
  • Export .glyph graph data to graph.json.
  • Generate a static index.html viewer.
  • Include work contexts, snapshots, publications, sources, content, claims, conflicts, hooks, remotes, and mounts.
  • Include an ordered operation timeline with audit, snapshot, publication, hook, and remote events.
  • Open locally without a server.
  • Let agents consume the same graph.json.