@gmickel/gno 1.7.0 → 1.8.0

package/README.md

@@ -92,9 +92,12 @@ gno daemon --detach  # headless continuous indexing (background; --status / --st
 
 ## What's New
 
-> Latest release: [v1.1.0](./CHANGELOG.md#110---2026-04-21)  
+> Latest release: [v1.8.0](./CHANGELOG.md#180---2026-06-05)  
 > Full release history: [CHANGELOG.md](./CHANGELOG.md)
 
+- **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
 - **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
@@ -543,6 +546,8 @@ 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
+- **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
 - **Connect agents**: Install core Skill/MCP integrations from the app

package/assets/skill/SKILL.md

@@ -136,7 +136,7 @@ gno search "error handling" --json | jq -r '.results[].uri' | xargs gno multi-ge
 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`; it also adds bounded one-hop graph neighbors from top seeds when graph data exists.
+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.
 
@@ -207,6 +207,34 @@ gno embed --collection travel
 
 MCP `gno.sync` and `gno.capture` do NOT auto-embed. Use CLI for embedding.
 
+## Capture Notes
+
+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
+```
+
+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
+unless `embed.status` is `completed`. Capture inputs must be text; binary-like
+file/stdin content is rejected before writing. CLI, REST, SDK, and Web capture
+writes fail instead of replacing late-arriving files; legacy `overwrite` is
+MCP-only.
+
+Programmatic capture uses the same receipt contract:
+
+- MCP: `gno_capture` (requires `gno mcp --enable-write`)
+- REST: `POST /api/capture`
+- SDK: `client.capture({ collection, content, source, tags })`
+
+MCP capture writes structured `source:` frontmatter, runs under the MCP write
+lock, syncs the file for FTS, and preserves legacy MCP fields (`docid`,
+`absPath`, `overwritten`, `serverInstanceId`) alongside the shared receipt. It
+does not auto-embed.
+
 ## Collection-specific embedding models
 
 Collections can override the global embedding model with `models.embed`.

package/assets/skill/cli-reference.md

@@ -111,6 +111,31 @@ Generate embeddings only.
 gno embed [--force] [--model <uri>] [--batch-size <n>] [--dry-run]
 ```
 
+## Capture
+
+### gno capture
+
+Capture a note into an editable collection with provenance.
+
+```bash
+gno capture "thought to remember"
+gno capture --stdin --collection notes --preset source-summary --tags inbox,gno
+gno capture --file ./clip.md --source-url https://example.com --source-kind web --json
+gno capture "meeting note" --quiet
+```
+
+Important behavior:
+
+- Inline content, `--stdin`, and `--file` are mutually exclusive.
+- Capture accepts text only; binary-like file/stdin content is rejected before
+  writing.
+- Without `--path`, `--folder`, or `--title`, captures use
+  `inbox/YYYY-MM-DD/capture-<body-hash>.md` in UTC.
+- Capture writes fail instead of replacing a late-arriving file.
+- `--json` returns a capture receipt with separate write, sync, and embed status.
+- Capture syncs the file into FTS but does not imply embedding unless
+  `embed.status` is `completed`.
+
 ## Search Commands
 
 ### gno search
@@ -154,7 +179,7 @@ gno query <query> [options]
 
 | Flag         | Time  | Description                    |
 | ------------ | ----- | ------------------------------ |
-| `--fast`     | ~0.7s | Skip expansion, graph, rerank  |
+| `--fast`     | ~0.7s | Skip expansion and rerank      |
 | (default)    | ~2-3s | Skip expansion, with reranking |
 | `--thorough` | ~5-8s | Full pipeline with expansion   |
 
@@ -164,7 +189,8 @@ Additional options:
 | ------------- | --------------------------------- |
 | `--no-expand` | Disable query expansion           |
 | `--no-rerank` | Disable reranking                 |
-| `--no-graph`  | Disable graph-neighbor candidates |
+| `--graph`     | Enable graph-neighbor candidates  |
+| `--no-graph`  | Compatibility no-op by default    |
 | `--explain`   | Print retrieval details to stderr |
 
 ### gno ask

package/assets/skill/examples.md

@@ -349,3 +349,19 @@ gno search "common term" --min-score 0.7
 # Get full content
 gno search "term" --full
 ```
+
+## Capture Notes
+
+### CLI capture with provenance
+
+```bash
+gno capture "thought to remember"
+gno capture --file ./clip.md --source-url https://example.com --source-kind web --json
+```
+
+### Web UI quick capture
+
+Press **N** in `gno serve`, write the note, and open **Source** only when you
+need provenance fields such as URL, author, observed date, or external id. The
+success view reports the write result, FTS sync state, and embed state
+separately.

package/assets/skill/mcp-reference.md

@@ -56,9 +56,8 @@ gno mcp status
 ## Retrieval Order
 
 For normal questions, start with `gno_query`, then read targeted snippets with
-`gno_get` or batch refs with `gno_multi_get`. `gno_query` already does bounded
-one-hop graph expansion from top seeds; pass `noGraph: true` only when comparing
-pure BM25/vector retrieval. Check `gno_status` first when freshness or
+`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.
 
 Use graph tools for relationship context: `gno_graph` for corpus report/stats,
@@ -69,6 +68,21 @@ community summaries,
 Graph edges include confidence/audit metadata; prefer `explicit` edges when
 answers depend on link certainty.
 
+## Capture
+
+`gno_capture` is available only when MCP starts with `--enable-write` or
+`GNO_MCP_ENABLE_WRITE=1`. It writes quick notes with structured `source:`
+frontmatter and returns the same provenance receipt shape as CLI, REST, and SDK
+capture, plus legacy MCP fields (`docid`, `absPath`, `overwritten`,
+`serverInstanceId`).
+
+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
+non-overwrite captures fail instead of replacing a late-arriving file. MCP
+capture syncs the file for FTS but does not auto-embed; run `gno_embed` or
+`gno_index` afterward when vector search should include it.
+
 ## Uninstall
 
 ```bash

package/package.json

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

@@ -0,0 +1,279 @@
+/**
+ * gno capture command implementation.
+ *
+ * @module src/cli/commands/capture
+ */
+
+// node:fs/promises for mkdir (no Bun equivalent for recursive dir creation)
+import { mkdir } from "node:fs/promises";
+// node:path has no Bun path utilities
+import { dirname, join } from "node:path";
+
+import type {
+  CapturePlan,
+  CaptureReceipt,
+  CaptureSourceKind,
+} from "../../core/capture";
+import type { NoteCollisionPolicy } from "../../core/note-creation";
+import type { NotePresetId } from "../../core/note-presets";
+
+import { getIndexDbPath } from "../../app/constants";
+import {
+  buildCaptureReceipt,
+  listCaptureDiskRelPaths,
+  planCapture,
+  serializeCaptureReceipt,
+} from "../../core/capture";
+import { writeCapturePlanFile } from "../../core/capture-write";
+import { withWriteLock } from "../../core/file-lock";
+import { defaultSyncService } from "../../ingestion";
+import { CliError } from "../errors";
+import { initStore } from "./shared";
+
+export interface CaptureCliOptions {
+  configPath?: string;
+  indexName?: string;
+  inlineContent?: string;
+  stdin?: boolean;
+  file?: string;
+  collection?: string;
+  title?: string;
+  path?: string;
+  folder?: string;
+  preset?: NotePresetId;
+  tags?: string;
+  collisionPolicy?: NoteCollisionPolicy;
+  sourceKind?: CaptureSourceKind;
+  sourceUrl?: string;
+  sourceTitle?: string;
+  sourceAuthor?: string;
+  sourceDate?: string;
+  sourceId?: string;
+}
+
+const SOURCE_KINDS = new Set<CaptureSourceKind>([
+  "direct",
+  "web",
+  "email",
+  "meeting",
+  "chat",
+  "file",
+  "api",
+  "unknown",
+]);
+const COLLISION_POLICIES = new Set<NoteCollisionPolicy>([
+  "error",
+  "open_existing",
+  "create_with_suffix",
+]);
+
+function parseTags(raw: string | undefined): string[] {
+  return (
+    raw
+      ?.split(",")
+      .map((tag) => tag.trim())
+      .filter((tag) => tag.length > 0) ?? []
+  );
+}
+
+async function readContent(
+  options: CaptureCliOptions
+): Promise<string | undefined> {
+  const sources = [
+    options.inlineContent?.trim().length ? "inline" : null,
+    options.stdin ? "stdin" : null,
+    options.file ? "file" : null,
+  ].filter((source) => source !== null);
+  if (sources.length > 1) {
+    throw new CliError(
+      "VALIDATION",
+      "Use only one content source: inline, --stdin, or --file."
+    );
+  }
+
+  if (options.stdin) {
+    return await Bun.stdin.text();
+  }
+  if (options.file) {
+    return await Bun.file(options.file).text();
+  }
+  return options.inlineContent;
+}
+
+function buildSource(options: CaptureCliOptions) {
+  if (options.sourceKind && !SOURCE_KINDS.has(options.sourceKind)) {
+    throw new CliError(
+      "VALIDATION",
+      "--source-kind must be one of: direct, web, email, meeting, chat, file, api, unknown"
+    );
+  }
+  return {
+    kind: options.sourceKind,
+    url: options.sourceUrl,
+    title: options.sourceTitle,
+    author: options.sourceAuthor,
+    observedAt: options.sourceDate,
+    externalId: options.sourceId,
+  };
+}
+
+function validateCollisionPolicy(
+  policy: NoteCollisionPolicy | undefined
+): void {
+  if (policy && !COLLISION_POLICIES.has(policy)) {
+    throw new CliError(
+      "VALIDATION",
+      "--collision-policy must be one of: error, open_existing, create_with_suffix"
+    );
+  }
+}
+
+export async function capture(
+  options: CaptureCliOptions
+): Promise<CaptureReceipt> {
+  const storeInit = await initStore({
+    configPath: options.configPath,
+    indexName: options.indexName,
+    syncConfig: true,
+  });
+  if (!storeInit.ok) {
+    throw new CliError("VALIDATION", storeInit.error);
+  }
+
+  const { store, collections } = storeInit;
+  try {
+    const collectionName = options.collection?.trim();
+    const collection = collectionName
+      ? collections.find(
+          (candidate) =>
+            candidate.name.toLowerCase() === collectionName.toLowerCase()
+        )
+      : collections[0];
+    if (!collection) {
+      throw new CliError(
+        "VALIDATION",
+        collectionName
+          ? `Collection not found: ${collectionName}`
+          : "No editable collection configured."
+      );
+    }
+
+    validateCollisionPolicy(options.collisionPolicy);
+    const content = await readContent(options);
+    const existingDocs = await store.listDocuments(collection.name);
+    if (!existingDocs.ok) {
+      throw new Error(existingDocs.error.message);
+    }
+    const diskRelPaths = await listCaptureDiskRelPaths(collection.path);
+    let plan: CapturePlan;
+    try {
+      plan = planCapture({
+        input: {
+          collection: collection.name,
+          content,
+          title: options.title,
+          relPath: options.path,
+          folderPath: options.folder,
+          collisionPolicy: options.collisionPolicy,
+          presetId: options.preset,
+          tags: parseTags(options.tags),
+          source: buildSource(options),
+        },
+        existingRelPaths: existingDocs.value.map((doc) => doc.relPath),
+        diskRelPaths,
+      });
+    } catch (error) {
+      throw new CliError(
+        "VALIDATION",
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+    const absPath = join(collection.path, plan.relPath);
+
+    const lockPath = join(
+      dirname(getIndexDbPath(options.indexName)),
+      ".mcp-write.lock"
+    );
+    return await withWriteLock(lockPath, async () => {
+      if (plan.openedExisting) {
+        const existingDoc = await store.getDocument(
+          collection.name,
+          plan.relPath
+        );
+        if (!existingDoc.ok) {
+          throw new Error(existingDoc.error.message);
+        }
+        return buildCaptureReceipt({
+          plan,
+          absPath,
+          docid: existingDoc.value?.docid,
+          sync: existingDoc.value
+            ? { status: "completed" }
+            : {
+                status: "skipped",
+                reason: "Existing file is not indexed yet.",
+              },
+        });
+      }
+
+      await mkdir(dirname(absPath), { recursive: true });
+      await writeCapturePlanFile(plan, absPath);
+      const syncResults = await defaultSyncService.syncFiles(
+        collection,
+        store,
+        [plan.relPath],
+        {
+          runUpdateCmd: false,
+          gitPull: false,
+        }
+      );
+      const syncResult = syncResults[0];
+      const docResult = await store.getDocument(collection.name, plan.relPath);
+      const docid = docResult.ok ? docResult.value?.docid : undefined;
+      return buildCaptureReceipt({
+        plan,
+        absPath,
+        docid: syncResult?.docid ?? docid,
+        sync:
+          syncResult?.status === "error"
+            ? {
+                status: "failed",
+                error:
+                  syncResult.errorMessage ??
+                  syncResult.errorCode ??
+                  "Unknown sync error",
+              }
+            : { status: "completed" },
+      });
+    });
+  } finally {
+    await store.close();
+  }
+}
+
+export function formatCaptureReceipt(
+  receipt: CaptureReceipt,
+  options: { json?: boolean; quiet?: boolean } = {}
+): string {
+  if (options.json) {
+    return serializeCaptureReceipt(receipt);
+  }
+  if (options.quiet) {
+    return receipt.uri;
+  }
+
+  const lines = [
+    receipt.openedExisting ? "Opened existing capture." : "Captured note.",
+    `URI: ${receipt.uri}`,
+    `Path: ${receipt.absPath ?? receipt.relPath}`,
+    `Sync: ${receipt.sync.status}`,
+    `Embed: ${receipt.embed.status}`,
+  ];
+  if (receipt.tags.length > 0) {
+    lines.push(`Tags: ${receipt.tags.join(", ")}`);
+  }
+  if (receipt.source.url) {
+    lines.push(`Source: ${receipt.source.url}`);
+  }
+  return lines.join("\n");
+}

package/src/cli/options.ts

@@ -38,6 +38,7 @@ export const CMD = {
   backlinks: "backlinks",
   similar: "similar",
   graph: "graph",
+  capture: "capture",
 } as const;
 
 export type CommandId = (typeof CMD)[keyof typeof CMD];
@@ -63,6 +64,7 @@ const FORMAT_SUPPORT: Record<CommandId, OutputFormat[]> = {
   [CMD.similar]: ["terminal", "json", "md"],
   // graph uses custom --dot/--mermaid flags (not OutputFormat) and writes via terminal output
   [CMD.graph]: ["json", "terminal"],
+  [CMD.capture]: ["terminal", "json"],
 };
 
 // ─────────────────────────────────────────────────────────────────────────────

package/src/cli/program.ts

@@ -247,6 +247,7 @@ export function createProgram(): Command {
   // Wire command groups
   wireSearchCommands(program);
   wireOnboardingCommands(program);
+  wireCaptureCommand(program);
   wireManagementCommands(program);
   wirePublishCommand(program);
   wireVecCommands(program);
@@ -539,7 +540,8 @@ function wireSearchCommands(program: Command): void {
     )
     .option("--no-expand", "disable query expansion")
     .option("--no-rerank", "disable reranking")
-    .option("--no-graph", "disable graph neighbor expansion")
+    .option("--graph", "enable graph neighbor expansion")
+    .option("--no-graph", "compatibility no-op; graph is off by default")
     .option(
       "--query-mode <mode:text>",
       "structured mode entry (repeatable): term:<text>, intent:<text>, or hyde:<text>",
@@ -656,6 +658,7 @@ function wireSearchCommands(program: Command): void {
         lineNumbers: Boolean(cmdOpts.lineNumbers),
         noExpand: depthPolicy.noExpand,
         noRerank: depthPolicy.noRerank,
+        graph: Boolean(cmdOpts.graph),
         noGraph: Boolean(cmdOpts.fast) || cmdOpts.graph === false,
         candidateLimit: depthPolicy.candidateLimit,
         queryModes,
@@ -1007,6 +1010,69 @@ function wireOnboardingCommands(program: Command): void {
     });
 }
 
+function wireCaptureCommand(program: Command): void {
+  program
+    .command("capture [content...]")
+    .description("Capture a note with provenance")
+    .option("--stdin", "read capture content from stdin")
+    .option("--file <path>", "read capture content from a text/markdown file")
+    .option("-c, --collection <name>", "target collection")
+    .option("--title <title>", "capture title")
+    .option("--path <relPath>", "explicit relative path inside collection")
+    .option("--folder <relPath>", "folder path inside collection")
+    .option("--preset <id>", "note preset scaffold")
+    .option("--tags <tags>", "comma-separated tags")
+    .option(
+      "--collision-policy <policy>",
+      "error, open_existing, or create_with_suffix"
+    )
+    .option(
+      "--source-kind <kind>",
+      "direct, web, email, meeting, chat, file, api, or unknown"
+    )
+    .option("--source-url <url>", "source URL")
+    .option("--source-title <title>", "source title")
+    .option("--source-author <author>", "source author")
+    .option("--source-date <date>", "source observed date/time")
+    .option("--source-id <id>", "source external id")
+    .option("--json", "JSON output")
+    .action(
+      async (contentParts: string[], cmdOpts: Record<string, unknown>) => {
+        const format = getFormat(cmdOpts);
+        assertFormatSupported(CMD.capture, format);
+        const globals = getGlobals();
+        const { capture, formatCaptureReceipt } =
+          await import("./commands/capture");
+        const receipt = await capture({
+          configPath: globals.config,
+          indexName: globals.index,
+          inlineContent:
+            contentParts.length > 0 ? contentParts.join(" ") : undefined,
+          stdin: Boolean(cmdOpts.stdin),
+          file: cmdOpts.file as string | undefined,
+          collection: cmdOpts.collection as string | undefined,
+          title: cmdOpts.title as string | undefined,
+          path: cmdOpts.path as string | undefined,
+          folder: cmdOpts.folder as string | undefined,
+          preset: cmdOpts.preset as never,
+          tags: cmdOpts.tags as string | undefined,
+          collisionPolicy: cmdOpts.collisionPolicy as never,
+          sourceKind: cmdOpts.sourceKind as never,
+          sourceUrl: cmdOpts.sourceUrl as string | undefined,
+          sourceTitle: cmdOpts.sourceTitle as string | undefined,
+          sourceAuthor: cmdOpts.sourceAuthor as string | undefined,
+          sourceDate: cmdOpts.sourceDate as string | undefined,
+          sourceId: cmdOpts.sourceId as string | undefined,
+        });
+        const output = formatCaptureReceipt(receipt, {
+          json: format === "json",
+          quiet: globals.quiet,
+        });
+        await writeOutput(output, format);
+      }
+    );
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Retrieval Commands (get, multi-get, ls)
 // ─────────────────────────────────────────────────────────────────────────────

package/src/core/capture-write.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared capture write semantics.
+ *
+ * @module src/core/capture-write
+ */
+
+import type { CapturePlan } from "./capture";
+
+import { atomicCreate, atomicWrite } from "./file-ops";
+
+function isFileExistsError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    "code" in error &&
+    typeof error.code === "string" &&
+    error.code === "EEXIST"
+  );
+}
+
+export async function writeCapturePlanFile(
+  plan: CapturePlan,
+  absPath: string
+): Promise<void> {
+  try {
+    if (plan.overwrite) {
+      await atomicWrite(absPath, plan.content);
+      return;
+    }
+    await atomicCreate(absPath, plan.content);
+  } catch (error) {
+    if (isFileExistsError(error)) {
+      throw new Error(
+        "File already exists. Use open_existing, create_with_suffix, or overwrite."
+      );
+    }
+    throw error;
+  }
+}