geronimo-iia/llm-wiki-skills/graph

Graph

The concept graph is built from the tantivy index — no file reads. Nodes are typed (by page type), edges are labeled (by x-graph-edges relation declarations in type schemas).

Edges come from two sources:

• Frontmatter fields (sources, concepts, document_refs,

superseded_by) — typed edges with relation labels

• Body [[wikilinks]] — generic links-to edges

Only pages that exist in the index are included. Broken references are silently skipped.

Edge system

The same frontmatter field has different relation labels depending on the page type. The engine reads x-graph-edges from the type's JSON Schema to determine the label.

Edge target type constraints are declared in x-graph-edges via target_types. The engine warns at ingest when an edge target has the wrong type.

Generate the graph

First call on any unfamiliar wiki

wiki_graph(format: "summary")

Returns aggregate metrics under 2KB — nodes, edges, by_type, top_hubs (top 10 by degree), relation_counts, isolated_count, communities. Use this to decide which filter to apply next before making a full graph call.

Output format is mermaid (default), dot, llms, json, or summary:

wiki_graph(format: "summary")   # aggregate metrics, under 2KB — start here
wiki_graph(format: "llms")      # natural language description, scoped subgraphs
wiki_graph(format: "mermaid")   # renderable diagram, scoped subgraphs only
wiki_graph(format: "dot")       # DOT diagram
wiki_graph(format: "json")      # full node/edge JSON

Mermaid output can be rendered directly in Markdown code blocks. Relation labels appear on edges. Node types map to CSS classes.

format: "llms" produces a natural language description of the graph structure: node counts by type, top hubs by degree, edge relation counts, and isolated nodes — directly readable without a renderer. Use it when the goal is interpretation, not visualization.

Filter the graph

Filters compose — combine any of them:

wiki_graph(type: "concept")
wiki_graph(relation: "fed-by")
wiki_graph(root: "<slug>", depth: 2)
wiki_graph(type: "concept", relation: "depends-on", root: "concepts/moe", depth: 2)

Unified cross-wiki graph:

wiki_graph(cross_wiki: true)

Merges all mounted wikis into a single graph. Each node is prefixed with its wiki name for disambiguation. Cross-wiki edges appear as resolved connections.

Single-wiki with cross-wiki targets: Without cross_wiki: true, pages linking to other wikis produce external placeholder nodes — visually distinct (dashed border in Mermaid/DOT) — showing that the link exists but the target lives in another space.

Interpret the graph

Recommended call sequence:

1. wiki_graph(format: "summary") — topology overview; identify dominant types, hub candidates, isolated count
2. wiki_graph(type: "<type>", format: "llms") — scoped natural language description; isolated titles capped at 20
3. wiki_graph(root: "<slug>", depth: 2) — subgraph for deep exploration
4. wiki_graph(format: "mermaid", root: "<slug>", depth: 2) — renderable diagram of scoped subgraph only; avoid on full graph (exceeds context limits at scale)

format: "llms" on unfiltered large wikis lists up to 20 isolated node titles then truncates with a count note directing to wiki_lint.

Analyze the graph structure for:

• Clusters — groups of tightly connected pages (knowledge domains)
• Isolated nodes — pages with no connections (potential orphans)
• Key hubs — pages with high degree (important concepts)
• Bridge nodes — pages connecting otherwise separate clusters; use wiki_lint(rules: "articulation-point,bridge") for deterministic identification
• Missing edges — concepts that should be linked but aren't

Community insights

When the wiki has ≥ 30 pages, call wiki_stats() and read the communities field:

• count — how many clusters exist; high count with low largest means a fragmented wiki
• largest / smallest — size range; a dominant cluster with many tiny communities means fragmentation
• For isolated pages, use wiki_lint(rules: "periphery,orphan") — richer output than communities stats; then wiki_suggest on flagged slugs for connection candidates

wiki_suggest results with reason: "same knowledge cluster" are cross-cluster candidates — thematically related pages with no direct link path. These are the highest-value link suggestions.

When communities is null (wiki below 30 pages), identify clusters manually from the Mermaid or DOT output.

wiki_stats() also returns structural topology fields when graph.structural_algorithms = true (default):

• diameter — longest shortest path; high value means the graph is elongated
• radius — minimum eccentricity; close to diameter means no strong center
• center — slugs with eccentricity equal to radius; these are the most

central hub pages — consider linking sparse nodes through them

• structural_note — non-null only when O(n²) algorithms were skipped due to

graph size (local_count > graph.max_nodes_for_diameter)

Suggest improvements

Based on the analysis:

• Missing links between related concepts
• Orphan pages that should connect to the main graph
• Overly connected hub pages that might need splitting
• Clusters that lack a section index page
• Edge target type mismatches (concept linking to wrong type)