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

Adds obsidian-wiki graph-query <vault> "<question>" — queries the compiled
wikilink index before opening any page bodies, returning ranked candidates,
a should_read shortlist, and multi-hop paths. Replaces the current approach
of opening 5-10 pages speculatively per query.

- New obsidian_wiki/graphrag.py: build_index() (frontmatter + wikilinks,
  in/out degree, tier), rank_candidates() (score = title/tag/summary match
  + degree bonus + tier weight), find_path() (BFS multi-hop, max_depth=4),
  classify_query() (direct/path/gap/list routing), query() top-level entry.
- index_only=true when top candidate has exact title match + non-empty
  summary — skips page reads entirely for lookup queries.
- CLI: graph-query <vault> "<question>" [--top N] [--max-read N] [--pretty]
- wiki-query SKILL.md gets Step 0: run graph-query first; use should_read
  instead of speculative reads; skip to Step 5 when index_only=true.
- 34 new tests: index building, ranking, path finding, query classification,
  integration, and CLI.

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",