Support external vault roots across tooling

AGENT_QUERY_GUIDE.md

@@ -9,7 +9,19 @@ last_reviewed: 2026-06-16
 
 # Agent Query Guide
 
-`index/graph.json` is for navigation. You can query tags or types there. Use it!
+`index/graph.json` is the selected vault's navigation index. MCP is the canonical
+cross-repository interface: `graph_summary`, `graph_search_nodes`,
+`graph_neighbors`, and `read_note`; use `refresh_graph(validate=true)` to update it.
+
+MCP-only agents use the tools above; shell examples below are for operators,
+not agent fallback. For those queries, explicitly set `KNOWLEDGE_BASE_ROOT` and change into
+that directory. Framework commands require `KNOWLEDGE_BASE_FRAMEWORK_ROOT` as
+an explicit path; skill or agent file locations do not identify the data vault.
+
+```bash
+: "${KNOWLEDGE_BASE_ROOT:?Set the data vault directory explicitly}"
+cd -- "$KNOWLEDGE_BASE_ROOT"
+```
 
 Schema:
 
@@ -22,7 +34,7 @@ Schema:
   - `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`, ...)
+  - `repo` (string): repo scope (a repository identifier, or `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
@@ -58,7 +70,7 @@ optional JSON brace suffix carrying the relationship and annotation:
   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`.
+  `python3 "$KNOWLEDGE_BASE_FRAMEWORK_ROOT/scripts/list-wiki-links.py" --vault-root "$KNOWLEDGE_BASE_ROOT"`.
 
 Examples with `jq`:
 
@@ -74,17 +86,17 @@ jq -r '[.nodes[].tags[]?] | group_by(.) | map({tag: .[0], count: length})
 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
+jq -r '.nodes[] | select(.repo=="<repo>") | "\(.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"
+NOTE_ID="<note-id>"
 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"
+NOTE_ID="<note-id>"
 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
@@ -104,11 +116,11 @@ 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
+python3 "$KNOWLEDGE_BASE_FRAMEWORK_ROOT/scripts/generate-graph.py" --vault-root "$KNOWLEDGE_BASE_ROOT" --validate
 
 # regenerate graph and validate
-python3 scripts/generate-graph.py && python3 scripts/generate-graph.py --validate
+python3 "$KNOWLEDGE_BASE_FRAMEWORK_ROOT/scripts/generate-graph.py" --vault-root "$KNOWLEDGE_BASE_ROOT" && python3 "$KNOWLEDGE_BASE_FRAMEWORK_ROOT/scripts/generate-graph.py" --vault-root "$KNOWLEDGE_BASE_ROOT" --validate
 
 # list any remaining legacy [[wiki links]] (rejected by --validate) to convert
-python3 scripts/list-wiki-links.py
+python3 "$KNOWLEDGE_BASE_FRAMEWORK_ROOT/scripts/list-wiki-links.py" --vault-root "$KNOWLEDGE_BASE_ROOT"
 ```