Merge pull request #123 from Ar9av/feat/graphrag-query

feat(graphrag): graph-index query pre-pass eliminates speculative page reads

Author: Ar9av

.skills/wiki-query/SKILL.md

@@ -56,6 +56,31 @@ In filtered mode, note the filter in the Step 6 log entry: `mode=filtered`.
 
 **Follow the Retrieval Primitives table in `llm-wiki/SKILL.md`.** Reading is the dominant cost of this skill — use the cheapest primitive that answers the question and escalate only when it can't. Never jump straight to full-page reads.
 
+### Step 0: GraphRAG Pre-pass (fast index query — no page reads)
+
+Before opening any pages, query the compiled graph index:
+
+```bash
+obsidian-wiki graph-query "$OBSIDIAN_VAULT_PATH" "<question>" --pretty
+```
+
+Output fields:
+
+- **`answer_type`**: `direct` | `path` | `list` | `gap` — shapes what to do next
+- **`candidates`**: top-ranked pages by title/tag/summary match + degree, with scores and summaries
+- **`should_read`**: the pages most worth opening — start here instead of speculatively reading many files
+- **`path`**: for multi-hop queries, the shortest wikilink path between the two concepts
+- **`god_nodes_relevant`**: hub pages related to your query terms — always useful context
+- **`index_only`**: if `true`, the top candidate's summary already answers the question — skip page reads
+
+**Decision tree:**
+
+1. If `index_only: true` → answer directly from `candidates[0].summary`. Skip Steps 1–4, go to Step 5.
+2. If `answer_type == "path"` and `path` is non-empty → the connection is in `path`. Read only those pages.
+3. Otherwise → open only `should_read` pages (not all candidates). This replaces the speculative 5–10 page reads the old flow required.
+
+**Fallback** (if `obsidian-wiki` is not installed): proceed with Step 1 as normal using grep and index.md.
+
 ### Step 1: Understand the Question
 
 Classify the query type:

obsidian_wiki/cli.py

@@ -349,6 +349,20 @@ def cmd_setup(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_graph_query(args: argparse.Namespace) -> int:
+    from obsidian_wiki.graphrag import query
+    vault = Path(args.vault).expanduser().resolve()
+    if not vault.is_dir():
+        print(f"error: vault not found: {vault}", file=sys.stderr)
+        return 1
+    result = query(vault, args.question, top_n=args.top, max_should_read=args.max_read)
+    if args.pretty:
+        print(json.dumps(result, indent=2))
+    else:
+        print(json.dumps(result))
+    return 0
+
+
 def cmd_batch_plan(args: argparse.Namespace) -> int:
     from obsidian_wiki.batch import plan_batches
     source_dir = Path(args.source_dir).expanduser().resolve()
@@ -491,6 +505,17 @@ def build_parser() -> argparse.ArgumentParser:
     ip = sub.add_parser("info", help="show install paths, version, and config")
     ip.set_defaults(func=cmd_info)
 
+    gq = sub.add_parser(
+        "graph-query",
+        help="answer a question from the vault's wikilink index without reading page bodies",
+    )
+    gq.add_argument("vault", help="path to the Obsidian vault")
+    gq.add_argument("question", help="question to answer")
+    gq.add_argument("--top", type=int, default=8, help="number of candidate pages to rank (default: 8)")
+    gq.add_argument("--max-read", type=int, default=3, help="max pages to return in should_read (default: 3)")
+    gq.add_argument("--pretty", action="store_true", help="pretty-print JSON output")
+    gq.set_defaults(func=cmd_graph_query)
+
     bp = sub.add_parser(
         "batch-plan",
         help="split a source directory into parallel-ingest batches, skipping unchanged files",