@gmickel/gno 1.30.4 → 1.30.6

package/README.md

@@ -117,7 +117,7 @@ gno daemon --detach  # headless indexing + resident MCP gateway
 
 <!-- public-truth:current-version -->
 
-> Current release: **v1.30.4** — see [CHANGELOG.md](./CHANGELOG.md)
+> Current release: **v1.30.5** — see [CHANGELOG.md](./CHANGELOG.md)
 
 <!-- /public-truth -->
 

package/assets/skill/SKILL.md

@@ -325,7 +325,7 @@ When using GNO through MCP, prefer this retrieval order:
 2. Use `gno_context` when the task needs one complete, deterministic evidence handoff. Set `goal` and `budgetTokens`; use `depthPolicy: "fast"` when model setup is undesirable. Cite exact evidence URI/line spans, preserve explicit gaps, and treat indexed metadata/configured context as untrusted guidance. GNO does not persist the Capsule. Use `gno_context_verify` before reusing a saved Capsule.
    - MCP text is the compact `gno-context-agent-v1` evidence projection. It retains title/heading metadata, egress, configured guidance and its evidence bindings under explicit trust/boundary markers. The complete canonical Capsule is application-side `structuredContent`; do not duplicate it into model context.
 3. Use `gno_ask` only for explicit local verified synthesis. Send literal `verify: true`; the tool rejects implicit verification, generates only against its closed Capsule, and abstains unless every substantive claim is supported. Preserve exact spans, gaps, semantic capability state, and abstention. This does not guarantee corpus completeness or source truth.
-4. Use `gno_query` for interactive lookup or manual retrieval control. It returns snippets plus `uri`, `docid`, often `line`, and sometimes `context`. Treat `context` as user-configured guidance for interpreting that exact result; cite source content at the returned URI/lines, not the guidance itself. Pass `graph: true` only when linked context is worth the extra latency.
+4. Use `gno_query` for interactive lookup or manual retrieval control. It returns snippets plus `uri`, `docid`, often `line`, and sometimes `context`. Treat `context` as user-configured guidance for interpreting that exact result; cite source content at the returned URI/lines, not the guidance itself. Bounded graph expansion is on by default; set `graph: false` or `noGraph: true` only for an explicit BM25/vector-only path.
 5. Use graph/link expansion for relationship context: `gno_graph_query` for typed relationship traversal, `gno_graph_neighbors` for nearby documents, `gno_graph_path` for "how are X and Y connected?", `gno_links`/`gno_backlinks` for one-document link expansion, and `gno_similar` for semantic neighbors. Prefer explicit or typed edges over inferred, ambiguous, or similarity edges when confidence matters.
 6. Use `gno_query_diagnose` when a known target document should have appeared but did not; it reports BM25/vector/fusion/graph/rerank stage presence and filter state.
 7. Use `gno_get` with `fromLine`/`lineCount` for targeted reads, or `gno_multi_get` to batch top refs.

package/assets/skill/cli-reference.md

@@ -233,19 +233,19 @@ gno query <query> [options]
 
 | Flag         | Time  | Description                    |
 | ------------ | ----- | ------------------------------ |
-| `--fast`     | ~0.7s | Skip expansion and rerank      |
-| (default)    | ~2-3s | Skip expansion, with reranking |
-| `--thorough` | ~5-8s | Full pipeline with expansion   |
+| `--fast`     | ~0.7s | Skip expansion, graph, rerank  |
+| (default)    | ~2-3s | Balanced, graph + reranking    |
+| `--thorough` | ~5-8s | Wider expansion + graph/rerank |
 
 Additional options:
 
-| Option        | Description                       |
-| ------------- | --------------------------------- |
-| `--no-expand` | Disable query expansion           |
-| `--no-rerank` | Disable reranking                 |
-| `--graph`     | Enable graph-neighbor candidates  |
-| `--no-graph`  | Compatibility no-op by default    |
-| `--explain`   | Print retrieval details to stderr |
+| Option        | Description                                |
+| ------------- | ------------------------------------------ |
+| `--no-expand` | Disable query expansion                    |
+| `--no-rerank` | Disable reranking                          |
+| `--graph`     | Explicitly enable default graph candidates |
+| `--no-graph`  | Disable graph-neighbor candidates          |
+| `--explain`   | Print retrieval details to stderr          |
 
 ### gno ask
 

package/assets/skill/mcp-reference.md

@@ -101,8 +101,9 @@ exact evidence handoff. Use `gno_ask` only when a local closed-evidence answer
 is specifically useful, and pass the literal boolean `verify: true`; it
 abstains unless every substantive claim is supported. This is a support
 classification against the retained Capsule, not a guarantee that the corpus
-is complete or its sources are true. Pass `graph: true` only when linked context
-is worth the extra latency. Check `gno_status` first when freshness or
+is complete or its sources are true. Bounded graph expansion is on by default;
+set `graph: false` or `noGraph: true` only for an explicit BM25/vector-only path.
+Check `gno_status` first when freshness or
 embeddings may be stale. Use `gno_query_diagnose` when a known target document
 should have appeared but did not.
 

package/browser-extension/artifacts/gno-browser-clipper-v1.30.6.zip.sha256

@@ -0,0 +1 @@
+20b500022a0f94f573aab83b4c2dd1626263f66141ffb3630fd7fd82cbc4254d  gno-browser-clipper-v1.30.6.zip

package/browser-extension/dist/manifest.json

@@ -21,5 +21,5 @@
   "content_security_policy": {
     "extension_pages": "script-src 'self'; object-src 'none'; connect-src http://127.0.0.1:*"
   },
-  "version": "1.30.4"
+  "version": "1.30.6"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.30.4",
+  "version": "1.30.6",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",

package/spec/cli.md

@@ -1173,8 +1173,8 @@ gno query diagnose <query> --target <doc> [-n <num>] [--min-score <num>] [-c <co
 |--------|------|-------------|
 | `--no-expand` | boolean | Disable query expansion |
 | `--no-rerank` | boolean | Disable cross-encoder reranking |
-| `--graph` | boolean | Enable bounded one-hop graph neighbor expansion |
-| `--no-graph` | boolean | Compatibility no-op; graph expansion is off unless `--graph` is passed |
+| `--graph` | boolean | Explicitly enable the default bounded one-hop graph neighbor expansion |
+| `--no-graph` | boolean | Disable graph neighbor expansion |
 | `--intent` | string | Disambiguating context for ambiguous queries; steers expansion, rerank chunk/snippet choice, and disables strong-signal bypass without being searched directly |
 | `--exclude` | string | Hard-prune docs containing any comma-separated term in title/path/body |
 | `-C, --candidate-limit` | integer | Max candidates passed to reranking (default 20) |
@@ -1188,11 +1188,11 @@ gno query diagnose <query> --target <doc> [-n <num>] [--min-score <num>] [-c <co
 **Compatibility / Migration:**
 
 - Legacy query invocations remain valid (`gno query "<text>"`, `--fast`, `--thorough`, `--no-expand`, `--no-rerank`).
-- `--fast` skips query expansion and reranking. Graph expansion is already off unless `--graph` is passed.
+- `--fast` skips query expansion, graph expansion, and reranking.
 - `--intent` is orthogonal to `--query-mode`: intent steers scoring/prompting, while query modes inject caller-provided retrieval expansions.
 - `--query-mode` is optional and additive to the command surface.
 - If one or more `--query-mode` entries are provided, generated expansion is bypassed and provided entries are used as retrieval intents.
-- By default, `gno query` does not expand through the document graph. Use `--graph` to add a capped one-hop graph-neighbor candidate set after BM25/vector retrieval. Explicit links are weighted above inferred, ambiguous, or similarity edges.
+- By default, balanced and thorough `gno query` retrieval adds a capped one-hop wiki/markdown-neighbor candidate set after BM25/vector retrieval. Use `--no-graph` to disable it. Query-time expansion resolves only links touching the top seeds; semantic similarity remains the vector stage's responsibility. Explicit links are weighted above inferred or ambiguous link matches.
 
 **Diagnose Output:**
 
@@ -1285,7 +1285,7 @@ Human-friendly query with citations-first output and optional grounded answer.
 **Synopsis:**
 
 ```bash
-gno ask <query> [-n <num>] [-c <collection>] [--lang <bcp47>] [--since <date>] [--until <date>] [--category <values>] [--author <text>] [--intent <text>] [--exclude <values>] [--query-mode <mode:text>]... [-C <num>] [--answer|--verify] [--no-answer] [--max-answer-tokens <n>] [--context-budget-tokens <n>] [--context-budget-bytes <n>] [--min-score <score>] [--graph] [--no-expand] [--no-rerank] [--explain] [--show-sources] [--json|--md]
+gno ask <query> [-n <num>] [-c <collection>] [--lang <bcp47>] [--since <date>] [--until <date>] [--category <values>] [--author <text>] [--intent <text>] [--exclude <values>] [--query-mode <mode:text>]... [-C <num>] [--answer|--verify] [--no-answer] [--max-answer-tokens <n>] [--context-budget-tokens <n>] [--context-budget-bytes <n>] [--min-score <score>] [--graph|--no-graph] [--no-expand] [--no-rerank] [--explain] [--show-sources] [--json|--md]
 ```
 
 **Options:**
@@ -1299,7 +1299,8 @@ gno ask <query> [-n <num>] [-c <collection>] [--lang <bcp47>] [--since <date>] [
 | `--context-budget-tokens` | integer  | 12000   | Global token budget for verified Context evidence                                  |
 | `--context-budget-bytes`  | integer  | none    | Optional global byte budget for verified Context evidence                          |
 | `--min-score`             | number   | none    | Minimum retrieval score from 0 through 1                                           |
-| `--graph`                 | boolean  | false   | Include bounded graph expansion in verified Context retrieval                      |
+| `--graph`                 | boolean  | true    | Include bounded graph expansion in verified Context retrieval                      |
+| `--no-graph`              | boolean  | false   | Disable graph expansion                                                            |
 | `--since`                 | string   | none    | Modified-at lower bound (ISO date/time or relative token)                          |
 | `--until`                 | string   | none    | Modified-at upper bound (ISO date/time or relative token)                          |
 | `--category`              | string   | none    | Filter to docs with matching category/content type (comma-separated)               |
@@ -1666,7 +1667,7 @@ written to stderr.
 **Synopsis:**
 
 ```bash
-gno context build "<goal>" --budget <tokens> [--collection <name>] [--project-root <path>]... [--no-project-affinity] [--fast|--thorough] [--json|--md] [--output <file>]
+gno context build "<goal>" --budget <tokens> [--collection <name>] [--project-root <path>]... [--no-project-affinity] [--graph|--no-graph] [--fast|--thorough] [--json|--md] [--output <file>]
 ```
 
 `--budget` is the global token ceiling. `--bytes` optionally sets a separate
@@ -1683,6 +1684,8 @@ Project affinity defaults to the trusted process cwd/repository. Repeatable
 `--project-root` values replace that default, are normalized/deduplicated, and
 are capped at 16. `--no-project-affinity` disables the soft signal and cannot
 be combined with explicit roots.
+Balanced and thorough Context retrieval request bounded graph expansion by
+default. `--no-graph` disables it; `--fast` also keeps the graph stage off.
 
 JSON is the canonical V1 payload. Markdown is a readable projection of that
 same payload and hard-delimits each untrusted evidence passage. Passage,

package/spec/mcp.md

@@ -158,6 +158,7 @@ Collection names are case-insensitive on input and normalized to lowercase in re
   for one goal. It compiles exact source spans, coverage gaps, omissions, and
   verification fingerprints in one call.
 - Prefer `gno_query` for normal questions. It is the default hybrid path and returns `uri`, `docid`, snippets, and `line` anchors for follow-up reads.
+- Bounded graph expansion is part of normal `gno_query` retrieval. Set `graph: false`, `noGraph: true`, or `fast: true` only when the caller explicitly wants to skip it.
 - Use `gno_search` for exact phrases, filenames, identifiers, error messages, and known symbols.
 - Use `gno_vsearch` for semantic similarity when wording differs and embeddings are current.
 - Use `intent` to disambiguate short or overloaded terms without changing the searched text.
@@ -675,13 +676,13 @@ Hybrid search combining BM25 and vector retrieval with optional expansion and re
     },
     "noGraph": {
       "type": "boolean",
-      "description": "Compatibility no-op unless graph is also true",
+      "description": "Disable graph neighbor expansion",
       "default": false
     },
     "graph": {
       "type": "boolean",
       "description": "Enable bounded one-hop graph neighbor expansion",
-      "default": false
+      "default": true
     },
     "fast": {
       "type": "boolean",
@@ -734,7 +735,7 @@ Compatibility / migration notes:
 - `intent` is orthogonal to `queryModes`: intent steers scoring/prompting, while query modes inject caller-provided retrieval expansions.
 - `candidateLimit` tunes rerank cost without changing retrieval contracts.
 - `exclude` hard-prunes matching docs after retrieval using title/path/body text.
-- `gno_query` does not use graph expansion by default. Set `graph: true` to add capped one-hop graph neighbors after initial retrieval. Explicit links receive stronger treatment than inferred, ambiguous, or similarity edges.
+- `gno_query` uses graph expansion by default. Set `graph: false` or `noGraph: true` to disable capped one-hop wiki/markdown neighbors. Query-time expansion resolves only links touching the top seeds; semantic similarity remains in vector retrieval. Explicit links receive stronger treatment than inferred or ambiguous link matches.
 - `queryModes` is optional; use it only when clients need explicit retrieval intent control.
 - When `queryModes` is present, generated expansion is skipped and provided entries are used directly.
 

package/src/app/context-runtime-input.ts

@@ -373,7 +373,7 @@ export const normalizeContextBuildInput = (
     minScore: input.minScore ?? null,
     since: temporalRange.since,
     until: temporalRange.until,
-    graph: input.graph ?? false,
+    graph: depthPolicy === "fast" ? false : (input.graph ?? true),
     noRerank: input.noRerank ?? false,
     limit,
     candidateLimit,

package/src/app/verified-ask.ts

@@ -191,7 +191,7 @@ export const buildVerifiedAsk = async (
       minScore: options.minScore,
       since: options.since,
       until: options.until,
-      graph: Boolean(options.graph && !options.noGraph),
+      graph: options.graph !== false && options.noGraph !== true,
       noRerank: options.noRerank,
       limit: options.limit ?? DEFAULT_VERIFIED_ASK_LIMIT,
       candidateLimit: options.candidateLimit,

package/src/cli/program.ts

@@ -856,15 +856,15 @@ function wireSearchCommands(program: Command): void {
     .option("--no-project-affinity", "disable project-aware ranking")
     .option("--full", "include full content")
     .option("--line-numbers", "include line numbers in output")
-    .option("--fast", "skip expansion and reranking (fastest, ~0.7s)")
+    .option("--fast", "skip query expansion, graph expansion, and reranking")
     .option(
       "--thorough",
       "use expansion with a wider rerank pool (slowest, best recall)"
     )
     .option("--no-expand", "disable query expansion")
     .option("--no-rerank", "disable reranking")
-    .option("--graph", "enable graph neighbor expansion")
-    .option("--no-graph", "compatibility no-op; graph is off by default")
+    .option("--graph", "enable graph neighbor expansion (default)")
+    .option("--no-graph", "disable graph neighbor expansion")
     .option("--target <doc>", "diagnose target document ref")
     .option(
       "--query-mode <mode:text>",
@@ -991,7 +991,7 @@ function wireSearchCommands(program: Command): void {
           ...projectAffinity,
           noExpand: depthPolicy.noExpand,
           noRerank: depthPolicy.noRerank,
-          graph: Boolean(cmdOpts.graph),
+          graph: cmdOpts.graph !== false,
           noGraph: Boolean(cmdOpts.fast) || cmdOpts.graph === false,
           candidateLimit: depthPolicy.candidateLimit,
           queryModes,
@@ -1029,7 +1029,7 @@ function wireSearchCommands(program: Command): void {
         lineNumbers: Boolean(cmdOpts.lineNumbers),
         noExpand: depthPolicy.noExpand,
         noRerank: depthPolicy.noRerank,
-        graph: Boolean(cmdOpts.graph),
+        graph: cmdOpts.graph !== false,
         noGraph: Boolean(cmdOpts.fast) || cmdOpts.graph === false,
         candidateLimit: depthPolicy.candidateLimit,
         queryModes,
@@ -1134,7 +1134,7 @@ function wireSearchCommands(program: Command): void {
       (value: string, previous: string[] = []) => [...previous, value],
       []
     )
-    .option("--fast", "skip expansion and reranking (fastest)")
+    .option("--fast", "skip query expansion, graph expansion, and reranking")
     .option(
       "--thorough",
       "use expansion with a wider rerank pool (slowest, best recall)"
@@ -1150,7 +1150,8 @@ function wireSearchCommands(program: Command): void {
     .option("--context-budget-tokens <num>", "verified Context token budget")
     .option("--context-budget-bytes <num>", "verified Context byte budget")
     .option("--min-score <score>", "minimum retrieval score (0-1)")
-    .option("--graph", "include bounded graph expansion")
+    .option("--graph", "include bounded graph expansion (default)")
+    .option("--no-graph", "disable graph neighbor expansion")
     .option("--explain", "include retrieval scoring explanation")
     .option(
       "--project-root <path>",
@@ -1255,7 +1256,8 @@ function wireSearchCommands(program: Command): void {
         intent: cmdOpts.intent as string | undefined,
         exclude,
         minScore,
-        graph: Boolean(cmdOpts.graph),
+        graph: !cmdOpts.fast && cmdOpts.graph !== false,
+        noGraph: Boolean(cmdOpts.fast) || cmdOpts.graph === false,
         queryModes,
         noExpand: depthPolicy.noExpand,
         noRerank: depthPolicy.noRerank,
@@ -2298,7 +2300,8 @@ function wireManagementCommands(program: Command): void {
     .option("--lang <code>", "language hint (BCP-47)")
     .option("--since <date>", "modified-at lower bound")
     .option("--until <date>", "modified-at upper bound")
-    .option("--graph", "enable graph neighbor expansion")
+    .option("--graph", "enable graph neighbor expansion (default)")
+    .option("--no-graph", "disable graph neighbor expansion")
     .option(
       "--project-root <path>",
       "trusted project root (repeatable; replaces cwd affinity)",
@@ -2306,7 +2309,7 @@ function wireManagementCommands(program: Command): void {
       []
     )
     .option("--no-project-affinity", "disable project-aware ranking")
-    .option("--fast", "use lexical-first fast retrieval")
+    .option("--fast", "use lexical-first retrieval without graph or rerank")
     .option("--thorough", "use a wider retrieval pool")
     .option("-n, --limit <num>", "maximum retrieved results")
     .option("-C, --candidate-limit <num>", "maximum rerank candidates")
@@ -2366,7 +2369,7 @@ function wireManagementCommands(program: Command): void {
         lang: cmdOpts.lang as string | undefined,
         since: cmdOpts.since as string | undefined,
         until: cmdOpts.until as string | undefined,
-        graph: Boolean(cmdOpts.graph),
+        graph: !cmdOpts.fast && cmdOpts.graph !== false,
         limit:
           cmdOpts.limit === undefined
             ? undefined

package/src/core/graph-edge-confidence.ts

@@ -0,0 +1,90 @@
+/**
+ * Shared confidence classification for resolved wiki/markdown graph edges.
+ * Kept in sync with getGraph so query-time seed expansion matches CLI/API graph.
+ *
+ * @module src/core/graph-edge-confidence
+ */
+
+import type { GraphEdgeAudit, GraphEdgeConfidence } from "../store/types";
+
+export const GRAPH_EDGE_CONFIDENCE_RANK: Record<GraphEdgeConfidence, number> = {
+  explicit: 1,
+  inferred: 2,
+  ambiguous: 3,
+  similarity: 4,
+};
+
+export function classifyResolvedGraphEdge(
+  linkType: "wiki" | "markdown",
+  matchRank: number | null,
+  matchCount: number | null
+): { confidence: GraphEdgeConfidence; audit: GraphEdgeAudit } {
+  if (linkType === "markdown") {
+    return {
+      confidence: "explicit",
+      audit: { resolution: "exact-path", matchCount: 1 },
+    };
+  }
+
+  const count = matchCount ?? 0;
+  if (count > 1) {
+    return {
+      confidence: "ambiguous",
+      audit: {
+        resolution: "ambiguous-fallback",
+        matchCount: count,
+      },
+    };
+  }
+
+  if (matchRank === 1 || matchRank === 2) {
+    return {
+      confidence: "explicit",
+      audit: { resolution: "exact-title", matchCount: count || 1 },
+    };
+  }
+  if (matchRank === 5 || matchRank === 6) {
+    return {
+      confidence: "explicit",
+      audit: { resolution: "exact-path", matchCount: count || 1 },
+    };
+  }
+
+  return {
+    confidence: "inferred",
+    audit: { resolution: "path-fallback", matchCount: count || 1 },
+  };
+}
+
+export function mergeGraphEdgeAudit(
+  current: {
+    confidence: GraphEdgeConfidence;
+    audit: GraphEdgeAudit;
+  },
+  nextConfidence: GraphEdgeConfidence,
+  nextAudit: GraphEdgeAudit
+): void {
+  if (
+    GRAPH_EDGE_CONFIDENCE_RANK[nextConfidence] <
+    GRAPH_EDGE_CONFIDENCE_RANK[current.confidence]
+  ) {
+    current.confidence = nextConfidence;
+    current.audit = {
+      ...nextAudit,
+      matchCount: Math.max(
+        current.audit.matchCount ?? 0,
+        nextAudit.matchCount ?? 0
+      ),
+    };
+    return;
+  }
+  if (
+    nextAudit.matchCount !== undefined &&
+    (current.audit.matchCount ?? 0) < nextAudit.matchCount
+  ) {
+    current.audit = {
+      ...current.audit,
+      matchCount: nextAudit.matchCount,
+    };
+  }
+}

package/src/mcp/tools/index.ts

@@ -110,7 +110,7 @@ export const MCP_TOOL_DESCRIPTIONS = {
   vsearch:
     "Vector semantic search. Finds conceptually similar docs with different wording. Structured results preserve optional user-configured context guidance. Best after embeddings are current; use intent to disambiguate short terms. Use gno_query for default hybrid retrieval.",
   query:
-    "Hybrid search (BM25 + vector + optional expansion/reranking). Recommended default. Structured results preserve optional user-configured context guidance with source identity. Use intent for ambiguous terms, queryModes to combine term/intent/hyde strategies, fast=true for quick lookup, thorough=true when recall matters, and candidateLimit to trade latency for coverage.",
+    "Hybrid search (BM25 + vector + default bounded graph expansion + optional query expansion/reranking). Recommended default. Structured results preserve optional user-configured context guidance with source identity. Use intent for ambiguous terms, queryModes to combine term/intent/hyde strategies, fast=true or graph=false for quick lookup, thorough=true when recall matters, and candidateLimit to trade latency for coverage.",
   queryDiagnose:
     "Diagnose why one target document does or does not appear for a query. Use when an important doc is missing, a filter may exclude it, or you need stage-by-stage BM25/vector/fusion/graph/rerank evidence before changing retrieval strategy.",
   get: "Retrieve one document by gno:// URI, docid (#abc123), or collection/path. After search results include line, pass fromLine and lineCount to fetch only the relevant range before expanding to the full document.",
@@ -559,7 +559,9 @@ export const queryInputSchema = z.object({
   fast: z
     .boolean()
     .default(false)
-    .describe("Skip expansion and reranking (~0.7s). Use for quick lookups"),
+    .describe(
+      "Skip query expansion, graph expansion, and reranking (~0.7s). Use for quick lookups"
+    ),
   thorough: z
     .boolean()
     .default(false)
@@ -574,14 +576,11 @@ export const queryInputSchema = z.object({
     .boolean()
     .optional()
     .describe("Override: enable/disable cross-encoder reranking"),
-  noGraph: z
-    .boolean()
-    .optional()
-    .describe("Compatibility no-op unless graph is also true"),
+  noGraph: z.boolean().optional().describe("Disable graph neighbor expansion"),
   graph: z
     .boolean()
     .optional()
-    .describe("Enable bounded one-hop graph neighbor expansion"),
+    .describe("Enable bounded one-hop graph neighbor expansion (default)"),
   explain: z
     .boolean()
     .optional()

package/src/mcp/tools/query.ts

@@ -255,7 +255,7 @@ export function handleQuery(
         author: args.author,
         noExpand,
         noRerank,
-        graph: args.graph === true,
+        graph: args.graph,
         noGraph: args.noGraph || args.fast,
         queryModes,
         tagsAll: normalizeTagFilters(args.tagsAll),
@@ -542,7 +542,7 @@ export function handleQueryDiagnose(
           author: args.author,
           noExpand,
           noRerank,
-          graph: args.graph === true,
+          graph: args.graph,
           noGraph: args.noGraph || args.fast,
           queryModes,
           tagsAll: normalizeTagFilters(args.tagsAll),

package/src/pipeline/graph-retrieval.ts

@@ -186,6 +186,46 @@ const addEdgeCandidate = (
   scores.set(neighborDocid, current + score);
 };
 
+const loadGraphLinks = async (
+  store: StorePort,
+  seedDocumentIds: number[],
+  options: {
+    collection?: string;
+    includeSimilar?: boolean;
+  }
+): Promise<
+  { ok: true; links: GraphLink[] } | { ok: false; reason: string }
+> => {
+  if (typeof store.getGraphNeighborsForSeeds === "function") {
+    const neighborsResult = await store.getGraphNeighborsForSeeds({
+      seedDocumentIds,
+      collection: options.collection,
+      limitEdges: GRAPH_EDGE_LIMIT,
+    });
+    if (!neighborsResult.ok) {
+      return { ok: false, reason: "graph_query_failed" };
+    }
+    return { ok: true, links: neighborsResult.value.links };
+  }
+
+  if (typeof store.getGraph !== "function") {
+    return { ok: false, reason: "graph_unavailable" };
+  }
+
+  // Compatibility fallback for mocks/adapters without the scoped method.
+  const graphResult = await store.getGraph({
+    collection: options.collection,
+    limitNodes: GRAPH_NODE_LIMIT,
+    limitEdges: GRAPH_EDGE_LIMIT,
+    includeSimilar: options.includeSimilar ?? false,
+    linkedOnly: true,
+  });
+  if (!graphResult.ok) {
+    return { ok: false, reason: "graph_query_failed" };
+  }
+  return { ok: true, links: graphResult.value.links };
+};
+
 /**
  * Expand top retrieval candidates through one-hop graph neighbors.
  */
@@ -225,7 +265,10 @@ export async function expandGraphCandidates(
     meta.fallbackReasons.push("graph_no_seed_candidates");
     return { candidates: [], meta };
   }
-  if (typeof store.getGraph !== "function") {
+  const hasScopedNeighbors =
+    typeof store.getGraphNeighborsForSeeds === "function";
+  const hasFullGraph = typeof store.getGraph === "function";
+  if (!hasScopedNeighbors && !hasFullGraph) {
     meta.fallbackReasons.push("graph_unavailable");
     return { candidates: [], meta };
   }
@@ -248,8 +291,7 @@ export async function expandGraphCandidates(
     return { candidates: [], meta };
   }
 
-  const seedByDocid = new Map<string, { doc: DocumentRow; rank: number }>();
-  const seedDocids = new Set<string>();
+  const rankedSeedDocs: Array<{ doc: DocumentRow; rank: number }> = [];
   for (const doc of seedDocsResult.value) {
     if (!doc.mirrorHash) {
       continue;
@@ -268,34 +310,48 @@ export async function expandGraphCandidates(
     if (rank <= 0) {
       continue;
     }
-    seedByDocid.set(doc.docid, { doc, rank });
-    seedDocids.add(doc.docid);
+    rankedSeedDocs.push({ doc, rank });
+  }
+  rankedSeedDocs.sort(
+    (left, right) =>
+      left.rank - right.rank ||
+      left.doc.id - right.doc.id ||
+      left.doc.docid.localeCompare(right.doc.docid)
+  );
+
+  const seedByDocid = new Map<string, { doc: DocumentRow; rank: number }>();
+  for (const seed of rankedSeedDocs) {
+    if (seedByDocid.size >= GRAPH_SEED_LIMIT) {
+      break;
+    }
+    if (!seedByDocid.has(seed.doc.docid)) {
+      seedByDocid.set(seed.doc.docid, seed);
+    }
   }
-  meta.seedCount = seedDocids.size;
-  if (seedDocids.size === 0) {
+  const seedDocids = new Set(seedByDocid.keys());
+  meta.seedCount = seedByDocid.size;
+  if (seedByDocid.size === 0) {
     meta.fallbackReasons.push("graph_seed_lookup_empty");
     return { candidates: [], meta };
   }
 
-  const graphResult = await store.getGraph({
+  const seedDocumentIds = [...seedByDocid.values()].map(({ doc }) => doc.id);
+  const linksResult = await loadGraphLinks(store, seedDocumentIds, {
     collection: options.collection,
-    limitNodes: GRAPH_NODE_LIMIT,
-    limitEdges: GRAPH_EDGE_LIMIT,
-    includeSimilar: options.includeSimilar ?? false,
-    linkedOnly: true,
+    includeSimilar: options.includeSimilar,
   });
-  if (!graphResult.ok) {
-    meta.fallbackReasons.push("graph_query_failed");
+  if (!linksResult.ok) {
+    meta.fallbackReasons.push(linksResult.reason);
     return { candidates: [], meta };
   }
-  if (graphResult.value.links.length === 0) {
+  if (linksResult.links.length === 0) {
     meta.fallbackReasons.push("graph_empty");
     return { candidates: [], meta };
   }
 
   const neighborScores = new Map<string, number>();
   const edgeConfidence = { ...EMPTY_EDGE_CONFIDENCE };
-  for (const link of graphResult.value.links) {
+  for (const link of linksResult.links) {
     const sourceSeed = seedByDocid.get(link.source);
     const targetSeed = seedByDocid.get(link.target);
     if (sourceSeed && !seedDocids.has(link.target)) {

package/src/pipeline/hybrid.ts

@@ -655,7 +655,7 @@ export async function searchHybrid(
     includeSimilar: vectorAvailable,
     limit,
     candidateLimit,
-    disabled: !options.graph || options.noGraph,
+    disabled: options.graph === false || options.noGraph === true,
     relPathPrefix: options.retrievalScope?.relPathPrefix,
     lang: options.lang,
     tagsAll: options.tagsAll,

package/src/pipeline/types.ts

@@ -244,7 +244,7 @@ export type HybridSearchOptions = SearchOptions & {
   explain?: boolean;
   /** Enable bounded one-hop graph candidate expansion */
   graph?: boolean;
-  /** Compatibility no-op unless graph is also true */
+  /** Explicitly disable graph neighbor expansion */
   noGraph?: boolean;
   /** Language hint for prompt selection (does NOT filter retrieval, only affects expansion prompts) */
   queryLanguageHint?: string;

package/src/serve/routes/api.ts

@@ -4079,7 +4079,7 @@ export async function handleQuery(
     queryModes: normalizedQueryModes,
     noExpand: body.noExpand,
     noRerank: body.noRerank,
-    graph: body.graph === true,
+    graph: body.graph,
     noGraph: body.noGraph,
     tagsAll,
     tagsAny,
@@ -4308,7 +4308,7 @@ export async function handleQueryDiagnose(
       queryModes: normalizedQueryModes,
       noExpand: body.noExpand,
       noRerank: body.noRerank,
-      graph: body.graph === true,
+      graph: body.graph,
       noGraph: body.noGraph,
       tagsAll,
       tagsAny,