@gmickel/gno 1.8.0 → 1.10.0

package/README.md

@@ -97,7 +97,11 @@ gno daemon --detach  # headless continuous indexing (background; --status / --st
 
 - **Second-brain capture**: `gno capture`, REST `/api/capture`, SDK
   `client.capture()`, MCP `gno_capture`, and Web UI Quick Capture write
-  provenance-rich notes from text, stdin, or files
+  provenance-rich notes from text, stdin, or files, including typed presets for
+  ideas, people, company/projects, and meetings
+- **Schema-lite content types**: optional `contentTypes` rules map configured
+  frontmatter `type` values or path prefixes to canonical `contentType` metadata
+  in JSON search/query results
 - **Publish to [gno.sh](https://gno.sh/publish)**: new `gno publish export` CLI and Web UI action produce a self-contained artifact you upload to the hosted reader — public, secret, invite-only, or locally encrypted before upload
 - **Retrieval Quality Upgrade**: stronger BM25 lexical handling, code-aware chunking, terminal result hyperlinks, and per-collection model overrides
 - **Code Embedding Benchmarks**: new benchmark workflow across canonical, real-GNO, and pinned OSS slices for comparing alternate embedding models
@@ -546,7 +550,7 @@ Open `http://localhost:3000` to:
 - **Browse**: Cross-collection tree workspace with folder detail panes and per-tab browse context
 - **Edit**: Create, edit, and delete documents with live preview
 - **Create in place**: New notes in the current folder/collection with presets and command-palette flows
-- **Capture with provenance**: `gno capture` and Web UI Quick Capture write quick notes to an editable collection with structured `source:` metadata and a receipt that separates write, sync, and embed state
+- **Capture with provenance**: `gno capture` and Web UI Quick Capture write quick notes to an editable collection with structured `source:` metadata, typed preset scaffolds, and a receipt that separates write, sync, and embed state
 - **Same capture contract everywhere**: CLI, MCP `gno_capture`, REST `/api/capture`, SDK `client.capture()`, and Web UI Quick Capture return the same provenance receipt shape
 - **Ask**: AI-powered Q&A with citations
 - **Manage Collections**: Add, remove, and re-index collections

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
 
@@ -214,8 +226,21 @@ Use `gno capture` for quick second-brain writes into an editable collection:
 ```bash
 gno capture "thought to remember"
 gno capture --file ./clip.md --source-url https://example.com --source-kind web --json
+gno capture --preset person --title "Jane Doe" --folder people/
+gno capture --preset meeting --title "Weekly sync" --folder meetings/
 ```
 
+Preset IDs: `blank`, `project-note`, `research-note`, `decision-note`,
+`prompt-pattern`, `source-summary`, `idea-original`, `person`,
+`company-project`, `meeting`.
+
+For second-brain pages, prefer the typed presets:
+
+- `idea-original`: exact idea phrasing, context, related concepts, publish potential.
+- `person`: current state, relationship, assessment, open threads, timeline.
+- `company-project`: state, changes, decisions, people, timeline.
+- `meeting`: synthesis/action analysis above `## Timeline`; raw notes below.
+
 The JSON receipt reports write, sync, and embed status separately. Generated
 captures land under `inbox/YYYY-MM-DD/capture-<body-hash>.md` unless `--path`,
 `--folder`, or `--title` overrides the path. Capture does not imply embedding

package/assets/skill/cli-reference.md

@@ -124,6 +124,15 @@ gno capture --file ./clip.md --source-url https://example.com --source-kind web
 gno capture "meeting note" --quiet
 ```
 
+Preset IDs: `blank`, `project-note`, `research-note`, `decision-note`,
+`prompt-pattern`, `source-summary`, `idea-original`, `person`,
+`company-project`, `meeting`.
+
+Second-brain presets keep current synthesis above `## Timeline` and dated
+evidence below it. Use `idea-original` for exact idea wording, `person` for
+relationship/current-state notes, `company-project` for organizations or active
+workstreams, and `meeting` for analysis above transcript/raw notes/action items.
+
 Important behavior:
 
 - Inline content, `--stdin`, and `--file` are mutually exclusive.
@@ -308,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

@@ -359,6 +359,47 @@ gno capture "thought to remember"
 gno capture --file ./clip.md --source-url https://example.com --source-kind web --json
 ```
 
+### Typed second-brain presets
+
+```bash
+# Original idea: preserve exact phrasing and related concepts
+gno capture --preset idea-original --title "Local-first inbox triage" --folder ideas/
+
+# Person page: current synthesis plus relationship/open threads/timeline
+gno capture --preset person --title "Jane Doe" --folder people/
+
+# Company/project page: state, decisions, people, and timeline
+gno capture --preset company-project --title "Acme renewal" --folder projects/
+
+# Meeting page: analysis above raw notes, transcript, and action items
+gno capture --preset meeting --title "Weekly sync" --folder meetings/
+```
+
+For these presets, keep current synthesis above `## Timeline`; put dated evidence
+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
@@ -76,6 +82,12 @@ frontmatter and returns the same provenance receipt shape as CLI, REST, and SDK
 capture, plus legacy MCP fields (`docid`, `absPath`, `overwritten`,
 `serverInstanceId`).
 
+`presetId` accepts `blank`, `project-note`, `research-note`, `decision-note`,
+`prompt-pattern`, `source-summary`, `idea-original`, `person`,
+`company-project`, or `meeting`. The typed second-brain presets use flat
+frontmatter (`type`, `category`, `tags`) and a synthesis/timeline page pattern;
+provenance still comes from the capture `source` fields, not the preset.
+
 Use `collisionPolicy: "open_existing"` to return an existing note without
 rewriting, `create_with_suffix` to create the next available path, or legacy
 `overwrite: true` to replace the target path. Capture content must be text, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "1.8.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/capture.ts

@@ -26,7 +26,7 @@ import {
 } from "../../core/capture";
 import { writeCapturePlanFile } from "../../core/capture-write";
 import { withWriteLock } from "../../core/file-lock";
-import { defaultSyncService } from "../../ingestion";
+import { defaultSyncService, withContentTypeRules } from "../../ingestion";
 import { CliError } from "../errors";
 import { initStore } from "./shared";
 
@@ -140,7 +140,7 @@ export async function capture(
     throw new CliError("VALIDATION", storeInit.error);
   }
 
-  const { store, collections } = storeInit;
+  const { store, collections, config } = storeInit;
   try {
     const collectionName = options.collection?.trim();
     const collection = collectionName
@@ -222,10 +222,13 @@ export async function capture(
         collection,
         store,
         [plan.relPath],
-        {
-          runUpdateCmd: false,
-          gitPull: false,
-        }
+        withContentTypeRules(
+          {
+            runUpdateCmd: false,
+            gitPull: false,
+          },
+          config
+        )
       );
       const syncResult = syncResults[0];
       const docResult = await store.getDocument(collection.name, plan.relPath);

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");
+}

package/src/cli/commands/index-cmd.ts

@@ -5,7 +5,11 @@
  * @module src/cli/commands/indexCmd
  */
 
-import { defaultSyncService, type SyncResult } from "../../ingestion";
+import {
+  defaultSyncService,
+  type SyncResult,
+  withContentTypeRules,
+} from "../../ingestion";
 import { formatSyncResultLines, initStore } from "./shared";
 
 /**
@@ -55,14 +59,21 @@ export async function index(options: IndexOptions = {}): Promise<IndexResult> {
     return { success: false, error: initResult.error };
   }
 
-  const { store, collections } = initResult;
+  const { store, collections, config } = initResult;
 
   try {
     // Run sync service (update phase)
-    const syncResult = await defaultSyncService.syncAll(collections, store, {
-      gitPull: options.gitPull,
-      runUpdateCmd: true,
-    });
+    const syncResult = await defaultSyncService.syncAll(
+      collections,
+      store,
+      withContentTypeRules(
+        {
+          gitPull: options.gitPull,
+          runUpdateCmd: true,
+        },
+        config
+      )
+    );
 
     // Embedding phase
     const embedSkipped = options.noEmbed ?? false;