Agent Query Guide

index/graph.json is for navigation. You can query tags or types there. Use it!

Schema:

Top-level object:
- version (number): schema version
- generated_at (string): ISO-8601 UTC timestamp
- nodes (array): note metadata records
- edges (array): directed wiki-link records
Node object (nodes[]):
- id (string): stable note identifier (usually from frontmatter)
- title (string): note title
- path (string): vault-relative markdown path
- repo (string): repo scope (tenant-controller, controller-util, global, ...)
- type (string): note classification (guideline, policy, project, etc.)
- status (string): lifecycle state (active, draft, deprecated)
- tags (string array): topic tags
- last_reviewed (string): YYYY-MM-DD
- outbound_links (string array): linked note IDs from this note
- inbound_count (number): number of edges targeting this note
Edge object (edges[]):
- from (string): source note ID
- to (string): target note ID
- kind (string): link mechanism — normally markdown_link (legacy wiki_link is rejected by --validate and should not appear in a valid graph)
- type (string): semantic relationship (see vocabulary below); default related
- anchor_text (string): display / alias text used in the link
- annotation (string): free-text "what the source needs from the destination" (from the link's link-info, falling back to a trailing — gloss); may be empty
- weight (number): link weight, currently 1.0

Link syntax

Links are standard markdown links whose target is the stable note id, with an optional JSON brace suffix carrying the relationship and annotation:

[display text](resource/old-deadlines){"type":"supersedes","link-info":"the deadline table this replaces"}

A bare [text](id) with no brace is a related edge.
type must be one of the controlled vocabulary; generate-graph.py --validate fails on any other value: related, supersedes, superseded-by, depends-on, part-of, parent, derived-from, see-also, source.
Legacy [[wiki links]] are no longer accepted: generate-graph.py --validate fails on any that remain. Locate and convert them with python3 scripts/list-wiki-links.py.

Examples with jq:

# list repos
jq -r '.nodes[].repo' index/graph.json | sort -u

# list top linked notes
jq -r '.nodes | sort_by(-(.inbound_count // 0))[] | "\(.inbound_count // 0)\t\(.id)\t\(.path)"' index/graph.json

# notes in one repo
jq -r '.nodes[] | select(.repo=="tenant-controller") | "\(.id)\t\(.path)"' index/graph.json

# all projects (PARA category 1)
jq -r '.nodes[] | select(.type=="project") | "\(.id)\t\(.path)"' index/graph.json

# outgoing links from one note
NOTE_ID="repo/controller-util/info"
jq -r --arg id "$NOTE_ID" '.nodes[] | select(.id==$id) | .outbound_links[]?' index/graph.json

# incoming links to one note
NOTE_ID="repo/controller-util/info"
jq -r --arg id "$NOTE_ID" '.edges[] | select(.to==$id) | .from' index/graph.json | sort -u

# outbound edges of a note WITH relationship type + annotation
jq -r --arg id "$NOTE_ID" '.edges[] | select(.from==$id) | "\(.type)\t\(.to)\t\(.annotation)"' index/graph.json

# all edges of a given relationship type (e.g. what supersedes what)
jq -r '.edges[] | select(.type=="supersedes") | "\(.from) -> \(.to)"' index/graph.json

# what a note supersedes
jq -r --arg id "$NOTE_ID" '.edges[] | select(.from==$id and .type=="supersedes") | .to' index/graph.json

For jg, use the same filters if your local jg is jq-compatible.

Validation:

# validate: non-zero exit on unresolved links, edge types outside the
# vocabulary, OR any remaining legacy [[wiki links]]
python3 scripts/generate-graph.py --validate

# regenerate graph and validate
python3 scripts/generate-graph.py && python3 scripts/generate-graph.py --validate

# list any remaining legacy [[wiki links]] (rejected by --validate) to convert
python3 scripts/list-wiki-links.py

4.1 KiB Raw Blame History

Agent Query Guide

Link syntax

4.1 KiB

Raw Blame History