@gmickel/gno 1.0.1 → 1.0.4

package/assets/skill/README.md

@@ -0,0 +1,130 @@
+# GNO — Agent Skill
+
+Local-first semantic search for documents, notes, and knowledge bases,
+packaged as a Claude Code / Codex / OpenCode / OpenClaw skill.
+
+> **TL;DR** — this folder is a runnable agent skill. Drop it into any
+> Claude Code, Codex, OpenCode, or OpenClaw workspace and the agent can
+> index and search your local files through the `gno` CLI.
+
+## Prerequisites
+
+You need the `gno` CLI installed locally. The skill drives it; it does
+not ship the binary itself.
+
+```bash
+# macOS / Linux
+curl -fsSL https://gno.sh/install | bash
+
+# npm / Bun
+bun add -g @gmickel/gno        # or: npm install -g @gmickel/gno
+```
+
+Verify: `gno --version` should print `1.0.3` or later.
+
+## Install the skill
+
+There are two ways to install, and which one you pick depends on where
+you're starting from.
+
+### Option A — install from your local `gno` (recommended if you already have GNO)
+
+If you already installed GNO, it ships this skill in-tree. One command
+drops it into the right place for every supported agent, always in sync
+with your installed GNO version:
+
+```bash
+gno skill install --target claude       # Claude Code (default)
+gno skill install --target codex        # OpenAI Codex CLI
+gno skill install --target opencode     # OpenCode
+gno skill install --target openclaw     # OpenClaw
+gno skill install --target all          # All four
+```
+
+Scope is configurable:
+
+```bash
+gno skill install --scope project       # ./.claude/skills/gno (default)
+gno skill install --scope user          # ~/.claude/skills/gno
+```
+
+Inspect or uninstall:
+
+```bash
+gno skill show                          # preview what would be installed
+gno skill paths                         # resolved installation paths
+gno skill uninstall --target all        # remove from all agents
+```
+
+This path always gives you the skill that matches your GNO CLI — no
+version drift.
+
+### Option B — install from ClawHub (recommended if you use OpenClaw)
+
+ClawHub is the OpenClaw skill registry. Use this when you manage
+skills centrally across multiple workspaces or when you don't have GNO
+installed yet.
+
+```bash
+openclaw skills install gno             # installs @gmickel/gno
+openclaw skills update gno              # pull a newer version later
+openclaw skills info gno                # inspect what's installed
+```
+
+You can also browse the skill at
+<https://clawhub.ai/gmickel/gno> and download the folder manually.
+
+## What the skill teaches the agent
+
+Once installed, the agent gains a single callable capability: run `gno`
+commands from the workspace. The skill docs (see [SKILL.md](SKILL.md))
+walk the model through:
+
+- initialising a new index and adding collections
+- keyword (`search`), vector (`vsearch`), hybrid (`query`) and
+  AI-answer (`ask`) search modes
+- document retrieval (`get`, `multi-get`) including line ranges
+- link graph traversal (`links`, `backlinks`, `similar`, `graph`)
+- tagging, contexts, and per-collection embedding models
+- publishing notes as gno.sh reader snapshots (`publish export`)
+- MCP server setup for persistent agent access
+
+The reference docs in this folder are discoverable by the agent via
+progressive disclosure — the model only pulls them when it needs them:
+
+- [SKILL.md](SKILL.md) — core instructions + frontmatter
+- [cli-reference.md](cli-reference.md) — every CLI command, option and flag
+- [mcp-reference.md](mcp-reference.md) — MCP tool and resource contract
+- [examples.md](examples.md) — end-to-end usage patterns
+
+## Agent tooling contract
+
+The skill requests two tools:
+
+```yaml
+allowed-tools: Bash(gno:*) Read
+```
+
+- **`Bash(gno:*)`** — the agent can invoke `gno <anything>` on the
+  host. All writes are explicit CLI calls; nothing runs implicitly.
+- **`Read`** — the agent can open files the user has pointed at. No
+  filesystem writes come through the skill itself.
+
+## Versioning
+
+The skill version is tracked separately from the GNO CLI version. When
+the CLI ships a new feature worth teaching the model (new flag, new
+subcommand, new sanitizer behaviour), the skill gets a point bump. See
+the CHANGELOG entry on ClawHub or the `gno` repo's CHANGELOG for what
+landed in each bump.
+
+## License
+
+MIT-0 — use it freely, with or without attribution.
+
+## Links
+
+- Source: <https://github.com/gmickel/gno>
+- Hosted publishing: <https://gno.sh>
+- OpenClaw docs: <https://docs.openclaw.ai>
+- ClawHub listing: <https://clawhub.ai/gmickel/gno>

package/assets/skill/cli-reference.md

@@ -504,24 +504,51 @@ Export a note or collection as a gno.sh publish artifact JSON.
 gno publish export <target> [--out <path.json>] [options]
 ```
 
-| Option         | Default | Description                                                   |
-| -------------- | ------- | ------------------------------------------------------------- |
-| `--out`        | auto    | Output path, defaults to `~/Downloads/<slug>-<YYYYMMDD>.json` |
-| `--visibility` | public  | One of `public`, `secret-link`, `invite-only`, `encrypted`    |
-| `--slug`       | auto    | Override the published route slug                             |
-| `--title`      | auto    | Override the exported title                                   |
-| `--summary`    | auto    | Override the exported summary                                 |
-| `--json`       | false   | Structured result output                                      |
+| Option         | Default | Description                                                                |
+| -------------- | ------- | -------------------------------------------------------------------------- |
+| `--out`        | auto    | Output path, defaults to `~/Downloads/<slug>-<YYYYMMDD>.json`              |
+| `--visibility` | public  | One of `public`, `secret-link`, `invite-only`, `encrypted`                 |
+| `--slug`       | auto    | Override the published route slug                                          |
+| `--title`      | auto    | Override the exported title                                                |
+| `--summary`    | auto    | Override the exported summary                                              |
+| `--passphrase` | none    | Required for `--visibility encrypted`; encrypts locally before upload      |
+| `--preview`    | false   | Print sanitized markdown + preprocessor report instead of writing artifact |
+| `--json`       | false   | Structured result output                                                   |
 
 Examples:
 
 ```bash
 gno publish export work-docs --out ~/Downloads/work-docs.json
 gno publish export "gno://work-docs/runbooks/deploy.md" --out ~/Downloads/deploy.json
+
+# Encrypted share — ciphertext produced locally before upload
+gno publish export "gno://work-docs/offer-letter.md" \
+  --visibility encrypted --passphrase "correct horse battery staple"
+
+# Inspect what the sanitizer strips before writing anything
+gno publish export "gno://vault/my-note.md" --preview
 ```
 
 On success, upload the JSON file at `https://gno.sh/studio`.
 
+**Obsidian pre-processor (v1.0.2+)**: before the artifact is written, the
+export pipeline runs a sanitizer over each note's markdown. It:
+
+- drops the navigation-sidebar idiom (`[[Hub]] | [[Related]]` immediately
+  under the frontmatter)
+- strips any `[[_internal/...]]` references (privacy guard — the
+  `_internal/` convention is treated as never-publish)
+- converts `[[Target|Alias]]` to the alias text, and `[[Target]]` to the
+  tail segment of the target
+- drops `![[image.png]]` embeds (attachments are not bundled yet) with a
+  warning so the author can migrate to `![alt](url)` or wait for bundling
+- refuses to export a note whose frontmatter contains `publish: false`
+  (single-note export errors; collection export silently skips)
+
+Every sanitizer decision surfaces in the CLI output as a "Preprocessor
+notes" section, on the `--json` response under `warnings`, and on
+`--preview` as a structured report — so nothing is silently lost.
+
 ## Skill Management
 
 ### gno skill install

package/package.json

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

package/src/cli/commands/publish.ts

@@ -13,9 +13,11 @@ import type {
   PublishArtifact,
   PublishVisibility,
 } from "../../publish/artifact";
+import type { SanitizeWarning } from "../../publish/obsidian-sanitize";
 
 import { derivePublishArtifactFilename, slugify } from "../../publish/artifact";
 import { exportPublishArtifact } from "../../publish/export-service";
+import { formatSanitizeWarnings } from "../../publish/obsidian-sanitize";
 import { initStore } from "./shared";
 
 export interface PublishExportOptions {
@@ -23,6 +25,7 @@ export interface PublishExportOptions {
   encryptionPassphrase?: string;
   json?: boolean;
   out?: string;
+  preview?: boolean;
   slug?: string;
   summary?: string;
   title?: string;
@@ -35,7 +38,10 @@ export type PublishExportResult =
       data: {
         artifact: PublishArtifact;
         outPath: string;
+        preview?: string;
         uploadUrl: string;
+        warnings: SanitizeWarning[];
+        warningsDisplay: string[];
       };
     }
   | { success: false; error: string; isValidation?: boolean };
@@ -73,7 +79,7 @@ export async function publishExport(
   const { collections, store } = initResult;
 
   try {
-    const artifact = await exportPublishArtifact({
+    const { artifact, warnings } = await exportPublishArtifact({
       collections,
       options: {
         routeSlug: options.slug,
@@ -85,6 +91,28 @@ export async function publishExport(
       store,
       target,
     });
+    const warningsDisplay = formatSanitizeWarnings(warnings);
+
+    if (options.preview) {
+      const preview =
+        artifact.version === 1
+          ? (artifact.spaces[0]?.notes
+              .map((note) => `\n# ${note.title}\n\n${note.markdown.trim()}`)
+              .join("\n\n---\n") ?? "")
+          : "(Encrypted artifact — preview unavailable)";
+      return {
+        success: true,
+        data: {
+          artifact,
+          outPath: "",
+          preview,
+          uploadUrl: "https://gno.sh/studio",
+          warnings,
+          warningsDisplay,
+        },
+      };
+    }
+
     const outPath =
       options.out?.trim() || buildDefaultPublishExportPath(artifact);
 
@@ -97,6 +125,8 @@ export async function publishExport(
         artifact,
         outPath,
         uploadUrl: "https://gno.sh/studio",
+        warnings,
+        warningsDisplay,
       },
     };
   } catch (error) {
@@ -129,8 +159,25 @@ export function formatPublishExport(
     return JSON.stringify(result.data, null, 2);
   }
 
-  const { artifact, outPath, uploadUrl } = result.data;
+  const { artifact, outPath, preview, uploadUrl, warningsDisplay } =
+    result.data;
   const space = artifact.spaces[0];
+  const warningsSection =
+    warningsDisplay.length > 0
+      ? ["", "Preprocessor notes:", ...warningsDisplay]
+      : [];
+
+  if (preview !== undefined) {
+    return [
+      `Preview (no file written) — ${space?.sourceType ?? "artifact"}`,
+      `Route slug: ${space?.routeSlug ?? slugify(artifact.source)}`,
+      `Visibility: ${space?.visibility ?? "public"}`,
+      ...warningsSection,
+      "",
+      "─── sanitized markdown ───",
+      preview.trim(),
+    ].join("\n");
+  }
 
   return [
     `Exported ${space?.sourceType ?? "artifact"} to ${outPath}`,
@@ -138,5 +185,6 @@ export function formatPublishExport(
     `Visibility: ${space?.visibility ?? "public"}`,
     `Filename: ${derivePublishArtifactFilename(artifact)}`,
     `Next: open ${uploadUrl} and drop ${outPath} into the upload zone.`,
+    ...warningsSection,
   ].join("\n");
 }

package/src/cli/program.ts

@@ -1651,6 +1651,10 @@ function wirePublishCommand(program: Command): void {
     .option("--slug <slug>", "route slug override")
     .option("--title <title>", "space title override")
     .option("--summary <summary>", "space summary override")
+    .option(
+      "--preview",
+      "print sanitized markdown + warnings instead of writing the artifact"
+    )
     .option("--json", "JSON output")
     .action(async (target: string, cmdOpts: Record<string, unknown>) => {
       const format = getFormat(cmdOpts);
@@ -1684,6 +1688,7 @@ function wirePublishCommand(program: Command): void {
         json: format === "json",
         out: typeof cmdOpts.out === "string" ? cmdOpts.out : undefined,
         encryptionPassphrase: passphrase,
+        preview: cmdOpts.preview === true,
         slug: cmdOpts.slug as string | undefined,
         summary: cmdOpts.summary as string | undefined,
         title: cmdOpts.title as string | undefined,

package/src/publish/export-service.ts

@@ -23,6 +23,11 @@ import {
   type PublishVisibility,
 } from "./artifact";
 import { buildEncryptedArtifactPayload } from "./encrypted-export";
+import {
+  isPublishDisabledByFrontmatter,
+  sanitizeObsidianMarkdown,
+  type SanitizeWarning,
+} from "./obsidian-sanitize";
 
 export interface PublishExportCoreOptions {
   encryptionPassphrase?: string;
@@ -129,7 +134,8 @@ async function exportCollectionArtifact(
   store: StorePort,
   collections: Collection[],
   target: string,
-  options: PublishExportCoreOptions
+  options: PublishExportCoreOptions,
+  warnings: SanitizeWarning[]
 ) {
   const collection = resolveCollection(collections, target);
   if (!collection) {
@@ -151,7 +157,13 @@ async function exportCollectionArtifact(
 
   const notes: PublishArtifactNote[] = [];
   for (const doc of activeDocs) {
-    const markdown = await loadDocumentMarkdown(store, doc);
+    const rawMarkdown = await loadDocumentMarkdown(store, doc);
+    if (isPublishDisabledByFrontmatter(rawMarkdown)) {
+      continue;
+    }
+    const sanitized = sanitizeObsidianMarkdown(rawMarkdown);
+    warnings.push(...sanitized.warnings);
+    const markdown = sanitized.markdown;
     const tags = await loadDocumentTags(store, doc);
     const frontmatter = parseFrontmatter(markdown).metadata;
     const title = deriveExportedTitle(doc);
@@ -164,6 +176,12 @@ async function exportCollectionArtifact(
     });
   }
 
+  if (notes.length === 0) {
+    throw new Error(
+      `Collection "${collection.name}" has no publishable documents (all notes carry publish: false frontmatter)`
+    );
+  }
+
   const title = options.title ?? collection.name;
   const summary =
     options.summary ??
@@ -217,14 +235,23 @@ async function exportCollectionArtifact(
 async function exportDocumentArtifact(
   store: StorePort,
   target: string,
-  options: PublishExportCoreOptions
+  options: PublishExportCoreOptions,
+  warnings: SanitizeWarning[]
 ) {
   const doc = await lookupDocument(store, target);
   if (!doc?.active) {
     throw new Error(`Document not found: ${target}`);
   }
 
-  const markdown = await loadDocumentMarkdown(store, doc);
+  const rawMarkdown = await loadDocumentMarkdown(store, doc);
+  if (isPublishDisabledByFrontmatter(rawMarkdown)) {
+    throw new Error(
+      `Refused to export: ${doc.uri} has publish: false in frontmatter`
+    );
+  }
+  const sanitized = sanitizeObsidianMarkdown(rawMarkdown);
+  warnings.push(...sanitized.warnings);
+  const markdown = sanitized.markdown;
   const tags = await loadDocumentTags(store, doc);
   const frontmatter = parseFrontmatter(markdown).metadata;
   const title = options.title ?? deriveExportedTitle(doc);
@@ -287,19 +314,31 @@ async function exportDocumentArtifact(
   });
 }
 
+export interface ExportPublishArtifactResult {
+  artifact: PublishArtifact;
+  warnings: SanitizeWarning[];
+}
+
 export async function exportPublishArtifact(input: {
   collections: Collection[];
   options: PublishExportCoreOptions;
   store: StorePort;
   target: string;
-}): Promise<PublishArtifact> {
-  return (
+}): Promise<ExportPublishArtifactResult> {
+  const warnings: SanitizeWarning[] = [];
+  const artifact =
     (await exportCollectionArtifact(
       input.store,
       input.collections,
       input.target,
-      input.options
+      input.options,
+      warnings
     )) ??
-    (await exportDocumentArtifact(input.store, input.target, input.options))
-  );
+    (await exportDocumentArtifact(
+      input.store,
+      input.target,
+      input.options,
+      warnings
+    ));
+  return { artifact, warnings };
 }

package/src/publish/obsidian-sanitize.ts

@@ -0,0 +1,176 @@
+/**
+ * Obsidian-aware markdown pre-processor for publish export.
+ *
+ * Strips wikilinks, drops navigation sidebar idioms, removes references to
+ * private (`_internal/`) paths, and warns on unresolvable image embeds before
+ * the markdown enters the publish artifact.
+ *
+ * @module src/publish/obsidian-sanitize
+ */
+
+const WIKILINK_INTERNAL_PREFIX = /_internal\//i;
+const NAV_SIDEBAR_LINE = /^(!?\[\[[^\]]+\]\]\s*\|?\s*)+$/;
+const IMAGE_EMBED = /!\[\[([^\]]+)\]\]/g;
+const INTERNAL_WIKILINK = /\[\[\s*_internal\/[^\]]+\]\]/gi;
+const ALIASED_WIKILINK = /\[\[([^\]|]+)\|([^\]]+)\]\]/g;
+const BARE_WIKILINK = /\[\[([^\]]+)\]\]/g;
+const TAIL_SEGMENT = /[^/]+$/;
+const BLOCK_ID_SUFFIX = /#\^?[\w-]+$/;
+
+export interface SanitizeWarning {
+  kind:
+    | "image-embed-dropped"
+    | "internal-reference-stripped"
+    | "nav-sidebar-dropped"
+    | "wikilink-unresolved";
+  detail: string;
+}
+
+export interface SanitizeResult {
+  markdown: string;
+  warnings: SanitizeWarning[];
+}
+
+const splitFrontmatter = (
+  source: string
+): { body: string; frontmatter: string } => {
+  if (!source.startsWith("---\n") && !source.startsWith("---\r\n")) {
+    return { body: source, frontmatter: "" };
+  }
+  const endIndex = source.indexOf("\n---\n");
+  const endIndexCrlf = source.indexOf("\r\n---\r\n");
+  const terminators = [endIndex, endIndexCrlf].filter((index) => index !== -1);
+  if (terminators.length === 0) {
+    return { body: source, frontmatter: "" };
+  }
+  const earliest = Math.min(...terminators);
+  const matched =
+    earliest === endIndex
+      ? source.slice(0, earliest + 5)
+      : source.slice(0, earliest + 7);
+  return {
+    body: source.slice(matched.length),
+    frontmatter: matched,
+  };
+};
+
+const deriveLinkDisplay = (target: string): string => {
+  const raw = target.trim();
+  const withoutBlockId = raw.replace(BLOCK_ID_SUFFIX, "").trim();
+  const tail = withoutBlockId.match(TAIL_SEGMENT)?.[0] ?? withoutBlockId;
+  return tail.trim() || raw;
+};
+
+export function sanitizeObsidianMarkdown(source: string): SanitizeResult {
+  const { body, frontmatter } = splitFrontmatter(source);
+  const warnings: SanitizeWarning[] = [];
+  const lines = body.split("\n");
+  const output: string[] = [];
+  let seenContent = false;
+
+  for (const rawLine of lines) {
+    const rawTrimmed = rawLine.trim();
+
+    if (!seenContent && rawTrimmed && NAV_SIDEBAR_LINE.test(rawTrimmed)) {
+      warnings.push({
+        kind: "nav-sidebar-dropped",
+        detail: rawTrimmed,
+      });
+      continue;
+    }
+
+    let line = rawLine;
+
+    line = line.replace(IMAGE_EMBED, (_match, target: string) => {
+      warnings.push({
+        kind: "image-embed-dropped",
+        detail: target.trim(),
+      });
+      return "";
+    });
+
+    line = line.replace(INTERNAL_WIKILINK, (match) => {
+      warnings.push({
+        kind: "internal-reference-stripped",
+        detail: match,
+      });
+      return "";
+    });
+
+    line = line.replace(
+      ALIASED_WIKILINK,
+      (_match, target: string, alias: string) => {
+        if (WIKILINK_INTERNAL_PREFIX.test(target)) {
+          warnings.push({
+            kind: "internal-reference-stripped",
+            detail: target.trim(),
+          });
+          return "";
+        }
+        return alias.trim();
+      }
+    );
+
+    line = line.replace(BARE_WIKILINK, (_match, target: string) => {
+      if (WIKILINK_INTERNAL_PREFIX.test(target)) {
+        warnings.push({
+          kind: "internal-reference-stripped",
+          detail: target.trim(),
+        });
+        return "";
+      }
+      const display = deriveLinkDisplay(target);
+      warnings.push({
+        kind: "wikilink-unresolved",
+        detail: target.trim(),
+      });
+      return display;
+    });
+
+    if (line.trim()) {
+      seenContent = true;
+    }
+
+    output.push(line);
+  }
+
+  return {
+    markdown: `${frontmatter}${output.join("\n")}`,
+    warnings,
+  };
+}
+
+const FRONTMATTER_PUBLISH_FALSE = /^publish:\s*(false|no|0)\s*$/im;
+
+export function isPublishDisabledByFrontmatter(source: string): boolean {
+  const { frontmatter } = splitFrontmatter(source);
+  if (!frontmatter) {
+    return false;
+  }
+  return FRONTMATTER_PUBLISH_FALSE.test(frontmatter);
+}
+
+export function formatSanitizeWarnings(warnings: SanitizeWarning[]): string[] {
+  const grouped = new Map<SanitizeWarning["kind"], Set<string>>();
+  for (const warning of warnings) {
+    const bucket = grouped.get(warning.kind) ?? new Set<string>();
+    bucket.add(warning.detail);
+    grouped.set(warning.kind, bucket);
+  }
+
+  const labels: Record<SanitizeWarning["kind"], string> = {
+    "image-embed-dropped": "Image embeds dropped (attachments not bundled yet)",
+    "internal-reference-stripped": "Private `_internal/` references stripped",
+    "nav-sidebar-dropped": "Navigation sidebar lines dropped",
+    "wikilink-unresolved":
+      "Wikilinks converted to plain text (no in-space target)",
+  };
+
+  return Array.from(grouped.entries()).flatMap(([kind, details]) => {
+    const lines = [`- ${labels[kind]}:`];
+    for (const detail of Array.from(details).sort()) {
+      lines.push(`    • ${detail}`);
+    }
+    return lines;
+  });
+}

package/src/serve/routes/api.ts

@@ -783,7 +783,7 @@ export async function handlePublishExport(
   }
 
   try {
-    const artifact = await exportPublishArtifact({
+    const { artifact, warnings } = await exportPublishArtifact({
       collections: config.collections,
       options: {
         encryptionPassphrase: body.encryptionPassphrase,
@@ -800,6 +800,7 @@ export async function handlePublishExport(
       artifact,
       fileName: derivePublishArtifactFilename(artifact),
       uploadUrl: "https://gno.sh/studio",
+      warnings,
     });
   } catch (error) {
     return errorResponse(