---
id: meta/agent-query-guide
title: Agent Query Guide
type: meta
status: active
tags: [agents, jq, graph]
last_reviewed: 2026-06-16
---

# 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 from a controlled vocabulary —
    `hub|project|area|guideline|policy|feature|roadmap|decision|note|meta|reference`;
    absent frontmatter means `note`, and `--validate` fails on anything else
  - `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:

```md
[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`:

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

# list the tag vocabulary, most frequent first (tags are matched verbatim)
jq -r '[.nodes[].tags[]?] | group_by(.) | map({tag: .[0], count: length})
  | sort_by(-.count)[] | "\(.count)\t\(.tag)"' index/graph.json

# 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:

```bash
# validate: non-zero exit on unresolved links, edge types or note types
# outside their vocabularies, 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
```