@gmickel/gno 1.9.0 → 1.10.0

package/assets/skill/SKILL.md

@@ -35,20 +35,20 @@ gno search "your query"               # BM25 keyword search
 
 ## Command Overview
 
-| Category     | Commands                                                         | Description                                               |
-| ------------ | ---------------------------------------------------------------- | --------------------------------------------------------- |
-| **Search**   | `search`, `vsearch`, `query`, `ask`                              | Find documents by keywords, meaning, or get AI answers    |
-| **Links**    | `links`, `backlinks`, `similar`, `graph`                         | Navigate document relationships and visualize connections |
-| **Retrieve** | `get`, `multi-get`, `ls`                                         | Fetch document content by URI or ID                       |
-| **Index**    | `init`, `collection add/list/remove`, `index`, `update`, `embed` | Set up and maintain document index                        |
-| **Tags**     | `tags`, `tags add`, `tags rm`                                    | Organize and filter documents                             |
-| **Context**  | `context add/list/rm/check`                                      | Add hints to improve search relevance                     |
-| **Models**   | `models list/use/pull/clear/path`                                | Manage local AI models                                    |
-| **Serve**    | `serve`                                                          | Web UI for browsing and searching                         |
-| **Publish**  | `publish export`                                                 | Export gno.sh publish artifacts                           |
-| **MCP**      | `mcp`, `mcp install/uninstall/status`                            | AI assistant integration                                  |
-| **Skill**    | `skill install/uninstall/show/paths`                             | Install skill for AI agents                               |
-| **Admin**    | `status`, `doctor`, `cleanup`, `reset`, `vec`, `completion`      | Maintenance and diagnostics                               |
+| Category     | Commands                                                         | Description                                            |
+| ------------ | ---------------------------------------------------------------- | ------------------------------------------------------ |
+| **Search**   | `search`, `vsearch`, `query`, `ask`                              | Find documents by keywords, meaning, or get AI answers |
+| **Links**    | `links`, `backlinks`, `similar`, `graph`, `graph query`          | Navigate document relationships and typed connections  |
+| **Retrieve** | `get`, `multi-get`, `ls`                                         | Fetch document content by URI or ID                    |
+| **Index**    | `init`, `collection add/list/remove`, `index`, `update`, `embed` | Set up and maintain document index                     |
+| **Tags**     | `tags`, `tags add`, `tags rm`                                    | Organize and filter documents                          |
+| **Context**  | `context add/list/rm/check`                                      | Add hints to improve search relevance                  |
+| **Models**   | `models list/use/pull/clear/path`                                | Manage local AI models                                 |
+| **Serve**    | `serve`                                                          | Web UI for browsing and searching                      |
+| **Publish**  | `publish export`                                                 | Export gno.sh publish artifacts                        |
+| **MCP**      | `mcp`, `mcp install/uninstall/status`                            | AI assistant integration                               |
+| **Skill**    | `skill install/uninstall/show/paths`                             | Install skill for AI agents                            |
+| **Admin**    | `status`, `doctor`, `cleanup`, `reset`, `vec`, `completion`      | Maintenance and diagnostics                            |
 
 ## Search Modes
 
@@ -137,8 +137,9 @@ When using GNO through MCP, prefer this retrieval order:
 
 1. Check `gno_status` first when freshness, missing vectors, or stale results are plausible.
 2. Use `gno_query` first for normal content questions. It returns snippets plus `uri`, `docid`, and often `line`; pass `graph: true` only when linked context is worth the extra latency.
-3. Use graph/link expansion for relationship context: `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` graph edges over `inferred`, `ambiguous`, or `similarity` edges when confidence matters.
-4. Use `gno_get` with `fromLine`/`lineCount` for targeted reads, or `gno_multi_get` to batch top refs.
+3. 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.
+4. 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.
+5. Use `gno_get` with `fromLine`/`lineCount` for targeted reads, or `gno_multi_get` to batch top refs.
 
 Use narrower tools when the request tells you to:
 
@@ -146,8 +147,10 @@ Use narrower tools when the request tells you to:
 - `gno_vsearch`: conceptual similarity when exact wording differs
 - `gno_status`: stale results, missing embeddings, vector unavailable
 - `gno_graph`: graph report/stats, hubs, isolates, unresolved links, edge confidence/audit, communities, unfamiliar corpus overview
+- `gno_graph_query`: bounded typed-edge traversal from a known document
 - `gno_graph_neighbors`: relationship/corpus-navigation questions around a known document
 - `gno_graph_path`: "how are X and Y connected?" questions
+- `gno_query_diagnose`: why a named target did or did not surface for a query
 
 For ambiguous terms, pass `intent` instead of bloating the query text. For typed retrieval, use `queryModes`: `term` for lexical anchors, `intent` for disambiguation, one `hyde` for a hypothetical answer/document.
 
@@ -160,6 +163,15 @@ gno links gno://notes/readme.md
 # Find documents linking TO a document (backlinks)
 gno backlinks gno://notes/api-design.md
 
+# Traverse typed relationships
+gno graph query gno://notes/people/alice.md --edge-type works_at --max-depth 2
+
+# Query semantic edges on link commands
+gno links gno://notes/people/alice.md --edge-type works_at
+
+# Diagnose a missing expected result
+gno query diagnose "Alice Acme" --target gno://notes/people/alice.md --json
+
 # Find semantically similar documents
 gno similar gno://notes/auth.md
 

package/assets/skill/cli-reference.md

@@ -317,6 +317,36 @@ gno backlinks <ref> [options]
 | `-n`     | Max results (default: 20) |
 | `--json` | JSON output               |
 
+`gno links` and `gno backlinks` also accept `--edge-type <type>` or
+`--relation <type>` to query semantic typed edges instead of positional
+wiki/markdown links. Do not combine `--type` with `--edge-type`.
+
+### gno graph query
+
+Bounded typed-edge traversal from a document.
+
+```bash
+gno graph query <ref> [--edge-type <type>] [--max-depth <n>] [--direction out|in|both] [--json]
+```
+
+Use this when relation meaning matters:
+
+```bash
+gno graph query gno://notes/people/alice.md --edge-type works_at --max-depth 2 --json
+```
+
+### gno query diagnose
+
+Explain why a target document did or did not surface for a query.
+
+```bash
+gno query diagnose "<query>" --target <ref> [--fast|--thorough] [--json]
+```
+
+The JSON output reports target status, filters, typed metadata, and per-stage
+presence across BM25, vector, fusion, graph expansion, and rerank. Use `--fast`
+for BM25-only diagnosis without vector/rerank startup.
+
 ### gno similar
 
 Find semantically similar documents.

package/assets/skill/examples.md

@@ -380,6 +380,26 @@ and raw chronology below it. If `contentTypes` are configured in `index.yml`,
 matching frontmatter `type` or path prefixes become `contentType` in JSON search
 results.
 
+### Typed relationships and diagnostics
+
+```yaml
+relations:
+  works_at: [gno://notes/companies/acme.md]
+  attended: [gno://notes/meetings/weekly-sync.md]
+```
+
+```bash
+# Traverse semantic relationships
+gno graph query gno://notes/people/alice.md --edge-type works_at --max-depth 2 --json
+
+# Query the semantic edge layer from link commands
+gno links gno://notes/people/alice.md --edge-type works_at
+gno backlinks gno://notes/meetings/weekly-sync.md --relation attended
+
+# Debug why a named target did not rank
+gno query diagnose "Alice Acme" --target gno://notes/people/alice.md --fast --json
+```
+
 ### Web UI quick capture
 
 Press **N** in `gno serve`, write the note, and open **Source** only when you

package/assets/skill/mcp-reference.md

@@ -58,16 +58,22 @@ gno mcp status
 For normal questions, start with `gno_query`, then read targeted snippets with
 `gno_get` or batch refs with `gno_multi_get`. Pass `graph: true` only when
 linked context is worth the extra latency. Check `gno_status` first when freshness or
-embeddings may be stale.
+embeddings may be stale. Use `gno_query_diagnose` when a known target document
+should have appeared but did not.
 
 Use graph tools for relationship context: `gno_graph` for corpus report/stats,
 community summaries,
+`gno_graph_query` for bounded typed-edge traversal,
 `gno_graph_neighbors` for nearby incoming/outgoing graph context, and
 `gno_graph_path` for "how are X and Y connected?" questions. Use
 `gno_links`, `gno_backlinks`, and `gno_similar` for one-document expansion.
 Graph edges include confidence/audit metadata; prefer `explicit` edges when
 answers depend on link certainty.
 
+Read-only MCP graph/query diagnostics include `gno_graph_query` and
+`gno_query_diagnose`. In `gno_query_diagnose`, pass `fast: true` for a BM25-only
+diagnosis that avoids embedding/rerank model initialization.
+
 ## Capture
 
 `gno_capture` is available only when MCP starts with `--enable-write` or

package/package.json

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

package/src/cli/commands/graph.ts

@@ -5,8 +5,15 @@
  * @module src/cli/commands/graph
  */
 
-import type { GetGraphOptions, GraphResult } from "../../store/types";
-
+import type {
+  GetGraphOptions,
+  GraphQueryDirection,
+  GraphQueryResult,
+  GraphResult,
+} from "../../store/types";
+
+import { normalizeContentTypes } from "../../config";
+import { diagnoseGraphQuery } from "../../core/graph-query";
 import { initStore } from "./shared";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -16,6 +23,8 @@ import { initStore } from "./shared";
 export interface GraphOptions {
   /** Override config path */
   configPath?: string;
+  /** Override index name */
+  indexName?: string;
   /** Filter by collection */
   collection?: string;
   /** Max nodes (default 2000) */
@@ -44,12 +53,28 @@ export interface GraphOptions {
   maxDepth?: number;
 }
 
+export interface GraphQueryCliOptions {
+  configPath?: string;
+  indexName?: string;
+  direction?: GraphQueryDirection;
+  edgeType?: string;
+  maxDepth?: number;
+  maxNodes?: number;
+  frontierLimit?: number;
+  visitedLimit?: number;
+  format?: "terminal" | "json";
+}
+
 export type GraphCommandResult =
   | { success: true; data: GraphResult }
   | { success: true; data: GraphNeighborsCliResult }
   | { success: true; data: GraphPathCliResult }
   | { success: false; error: string; isValidation?: boolean };
 
+export type GraphQueryCommandResult =
+  | { success: true; data: GraphQueryResult }
+  | { success: false; error: string; isValidation?: boolean };
+
 type GraphNode = GraphResult["nodes"][number];
 type GraphLink = GraphResult["links"][number];
 
@@ -94,6 +119,7 @@ export async function graph(
 ): Promise<GraphCommandResult> {
   const initResult = await initStore({
     configPath: options.configPath,
+    indexName: options.indexName,
     syncConfig: false,
   });
   if (!initResult.ok) {
@@ -185,6 +211,35 @@ export async function graph(
   }
 }
 
+export async function graphQuery(
+  docRef: string,
+  options: GraphQueryCliOptions = {}
+): Promise<GraphQueryCommandResult> {
+  const initResult = await initStore({
+    configPath: options.configPath,
+    indexName: options.indexName,
+    syncConfig: false,
+  });
+  if (!initResult.ok) {
+    return { success: false, error: initResult.error };
+  }
+  const { store, config } = initResult;
+
+  try {
+    return await diagnoseGraphQuery(store, docRef, {
+      direction: options.direction,
+      edgeType: options.edgeType,
+      maxDepth: options.maxDepth,
+      maxNodes: options.maxNodes,
+      frontierLimit: options.frontierLimit,
+      visitedLimit: options.visitedLimit,
+      contentTypeRules: normalizeContentTypes(config.contentTypes ?? []).rules,
+    });
+  } finally {
+    await store.close();
+  }
+}
+
 function resolveGraphNode(
   graphResult: GraphResult,
   ref: string
@@ -421,3 +476,35 @@ export function formatGraph(
       return JSON.stringify(data, null, 2);
   }
 }
+
+export function formatGraphQuery(
+  result: GraphQueryCommandResult,
+  options: GraphQueryCliOptions
+): string {
+  if (!result.success) {
+    if (options.format === "json") {
+      return JSON.stringify({
+        error: { code: "GRAPH_QUERY_FAILED", message: result.error },
+      });
+    }
+    return `Error: ${result.error}`;
+  }
+
+  if (options.format === "json") {
+    return JSON.stringify(result.data, null, 2);
+  }
+
+  const lines = [
+    `Graph query from ${result.data.root.uri}`,
+    `Nodes: ${result.data.meta.returnedNodes}, edges: ${result.data.meta.returnedEdges}`,
+  ];
+  if (result.data.meta.truncated) {
+    lines.push(`Truncated: ${result.data.meta.warnings.join("; ")}`);
+  }
+  for (const edge of result.data.edges) {
+    lines.push(
+      `${edge.source} -> ${edge.target} (${edge.edgeType}, ${edge.confidence}, ${edge.edgeSource}, depth ${edge.depth})`
+    );
+  }
+  return lines.join("\n");
+}