Norn/README.md
2026-04-29 21:28:47 +01:00

208 lines
5.5 KiB
Markdown

# EpiphanyGraph
Small .NET tool for turning an Obsidian note subtree into an MSAGL layout. It still works as a CLI, and now it can also sit on stdio as an MCP server.
## What It Does
- scans markdown notes under a vault folder
- resolves Obsidian wikilinks and regular markdown note links
- optionally starts from an entry note and keeps only reachable notes
- classifies notes into `source-tree` and `control-flow` graph families
- lays out each family as its own graph partition
- reports cross-links that still jump between those families
- runs Microsoft Automatic Graph Layout
- writes:
- `manifest.json`
- `source-tree.svg`
- `source-tree.msagl.svg`
- `source-tree.rich.svg`
- `source-tree.json`
- `control-flow.svg`
- `control-flow.msagl.svg`
- `control-flow.rich.svg`
- `control-flow.json`
- `cross-links.json`
- `warnings.txt`
## CLI Usage
Run from source:
```powershell
dotnet run --project . -- `
--vault-root "E:\Projects\Aetheria-Economy\Aetheria\Source Tree Map" `
--entry-note "Source Tree Map" `
--renderer rich `
--output-dir ".\out\source-tree-map"
```
After packing as a .NET tool:
```powershell
epiphanygraph `
--vault-root "E:\Projects\Aetheria-Economy\Aetheria\Source Tree Map" `
--entry-note "Source Tree Map" `
--renderer rich `
--output-dir ".\out\source-tree-map"
```
## MCP Usage
The MCP server exposes one tool:
- `generate_obsidian_graph_layout`
### Run From Source
Use this in an MCP client config when you want to launch the server straight from the repo:
```json
{
"mcpServers": {
"epiphanygraph": {
"command": "dotnet",
"args": [
"run",
"--project",
"E:\\Projects\\EpiphanyGraph\\EpiphanyGraph.csproj",
"--",
"--mcp"
]
}
}
}
```
### Pack As A .NET Tool
Build the package:
```powershell
dotnet pack . -c Release -o .\nupkg
```
Install it from the local package output:
```powershell
dotnet tool install --global --add-source .\nupkg EpiphanyGraph
```
Then point your MCP client at the installed command:
```json
{
"mcpServers": {
"epiphanygraph": {
"command": "epiphanygraph",
"args": ["--mcp"]
}
}
}
```
### MCP Tool Arguments
- `vaultRoot`: path to the Obsidian vault folder
- `entryNote`: optional entry note name or relative note path
- `outputDir`: optional output directory, defaults to `./out`
- `layout`: `sugiyama` or `mds`
- `renderer`: `msagl` or `rich`
- `includeUnreachable`: keep notes that are not reachable from the entry note
### MCP Tool Result
The tool writes `manifest.json`, primary partition SVGs, raw `.msagl.svg` variants, custom `.rich.svg` variants, partition JSON files, `cross-links.json`, and `warnings.txt`, then returns:
- output paths for each partition
- seed note IDs used for traversal
- total note and edge counts
- per-partition node and edge counts
- warnings
- the resolved entry note ID, if one was used
## Graph Families
By default, notes whose basename contains `Control Flow` land in the `control-flow` partition, and everything else lands in `source-tree`.
You can override that with frontmatter on a note:
```yaml
---
epiphany-graph-family: control-flow
---
```
or:
```yaml
---
epiphany-graph-families:
- source-tree
- control-flow
---
```
Supported keys:
- `epiphany-graph-family`
- `epiphany-graph-families`
- `graph-family`
- `graph-families`
If your chosen `entryNote` is itself one of the explicit family roots, the generator also seeds traversal from any sibling family roots it can find.
- `Source Tree Map` will also pull in `Control Flow Map`
- `Control Flow Map` will also pull in `Source Tree Map`
That keeps structurally separated note graphs from vanishing just because they no longer link to each other directly.
## Layout Modes
- `sugiyama`: layered, better for hierarchy-heavy note trees
- `mds`: force-ish spread, better when the graph is cross-linked chaos
`mds` is the closest MSAGL-native approximation to the Obsidian or Kamada-Kawai vibe. It is not a named Kamada-Kawai mode.
## Renderer Modes
- `msagl`: the stock MSAGL SVG, useful as the plain baseline
- `rich`: a custom SVG renderer that consumes MSAGL graph geometry and semantic metadata, then draws something with more visual hierarchy and less beige despair
## ELK Probe
There is also a small web-side `elkjs` probe under `web/elk-probe/`. It inspects which algorithms and options are actually present in the installed `elkjs` build and can relayout existing `source-tree.json` / `control-flow.json` outputs without crossing the C# boundary.
## Epiphany Graph Viewer
There is now also a real web-side viewer package under `web/epiphany-graph-viewer/`.
It consumes the typed Epiphany graph state shape directly:
- `graphs.architecture`
- `graphs.dataflow`
- `graphs.links`
and packages:
- `elkjs` layout
- zoom and pan
- zoom-gated label and detail pop-in
- node, edge, and code-ref inspection
- typed cross-link browsing between architecture and dataflow
Run it locally with:
```powershell
cd E:\Projects\EpiphanyGraph\web\epiphany-graph-viewer
npm install
npm run dev
```
## Notes
- unresolved and ambiguous links are written to `warnings.txt`
- node IDs in the partition `.json` files are relative note paths without `.md`
- the current implementation estimates label sizes instead of using a platform text measurer, because this is a generator, not a cathedral
- `source-tree.svg` and `control-flow.svg` are the primary outputs for the selected renderer
- raw MSAGL output is always preserved as `*.msagl.svg`
- the custom renderer currently emits `*.rich.svg` from MSAGL geometry, not from post-processing the stock SVG