109 lines
4.1 KiB
Markdown
109 lines
4.1 KiB
Markdown
---
|
|
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 (`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:
|
|
|
|
```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 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 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
|
|
```
|