@gmickel/gno 0.41.1 → 0.42.0

package/README.md

@@ -8,6 +8,9 @@
 [![Twitter](./assets/badges/twitter.svg)](https://twitter.com/gmickel)
 [![Discord](./assets/badges/discord.svg)](https://discord.gg/nHEmyJB5tg)
 
+> [!TIP]
+> **[gno.sh/publish](https://gno.sh/publish) is live.** Turn any GNO note or collection into a polished, reader-first URL — editorial typography, scoped search, and four visibility modes from public to end-to-end encrypted. **[See the reader →](#publish-to-gnosh)**
+
 > **ClawdHub**: GNO skills bundled for Clawdbot — [clawdhub.com/gmickel/gno](https://clawdhub.com/gmickel/gno)
 
 ![GNO](./assets/og-image.png)
@@ -27,6 +30,7 @@ Use it when:
 - **Real retrieval surfaces**: CLI, Web UI, REST API, MCP, SDK
 - **Local-first answers**: grounded synthesis with citations when you want answers, raw retrieval when you do not
 - **Connected knowledge**: backlinks, related notes, graph view, cross-collection navigation
+- **Shareable, not synced**: export a note or collection to [gno.sh](https://gno.sh/publish) as a polished reader page — public, secret, invite-only, or end-to-end encrypted
 - **Operational fit**: daemon mode, model presets, remote GPU backends, safe config/state on disk
 
 ### One-Minute Tour
@@ -74,6 +78,7 @@ gno daemon
 - [Search Modes](#search-modes)
 - [Agent Integration](#agent-integration)
 - [Web UI](#web-ui)
+- [Publish to gno.sh](#publish-to-gnosh)
 - [REST API](#rest-api)
 - [SDK](#sdk)
 - [How It Works](#how-it-works)
@@ -90,6 +95,7 @@ gno daemon
 > Latest release: [v0.40.2](./CHANGELOG.md#0402---2026-04-06)  
 > Full release history: [CHANGELOG.md](./CHANGELOG.md)
 
+- **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 end-to-end encrypted
 - **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
 - **Default Embed Model**: built-in presets now use `Qwen3-Embedding-0.6B-GGUF` after it beat `bge-m3` on both code and multilingual prose benchmark lanes
@@ -410,8 +416,22 @@ gno query "refresh token rotation" --explain
 # Work with filters
 gno query "meeting notes" --since "last month" --category "meeting,notes"
 gno search "incident review" --tags-all "status/active,team/platform"
+
+# Export a publish artifact for gno.sh
+gno publish export work-docs --out ~/Downloads/work-docs.json
+gno publish export "gno://work-docs/runbooks/deploy.md" --out ~/Downloads/deploy.json
+# Or let GNO choose ~/Downloads/<slug>-<YYYYMMDD>.json automatically
+gno publish export work-docs
 ```
 
+The local web UI exposes the same export flow:
+
+- Collections page → collection menu → `Export for gno.sh`
+- Document view → `Export for gno.sh`
+
+Both actions download the same JSON artifact the CLI writes, ready for upload at
+`https://gno.sh/studio`.
+
 ### Retrieval V2 Controls
 
 Existing query calls still work. Retrieval v2 adds optional structured intent control and deeper explain output.
@@ -590,6 +610,47 @@ Everything runs locally. No cloud, no accounts, no data leaving your machine.
 
 ---
 
+## Publish to gno.sh
+
+GNO is local-first, but sometimes you want a URL to send someone. [**gno.sh**](https://gno.sh/publish) is the hosted reader on top of GNO — a polished, reading-first page for a single note or a whole collection, without mounting your vault or syncing anything.
+
+![gno.sh publish reader](./assets/screenshots/publish-reader.jpg)
+
+The workflow is deliberately explicit: **export locally → upload artifact → share URL**. Your private notes and metadata stay on your machine. Only what you export leaves.
+
+```bash
+# Export a single note
+gno publish export "gno://work-docs/runbooks/deploy.md" --out ~/Downloads/deploy.json
+
+# Export a whole collection
+gno publish export work-docs --out ~/Downloads/work-docs.json
+
+# Let GNO pick the path (~/Downloads/<slug>-<YYYYMMDD>.json)
+gno publish export work-docs
+```
+
+Or use the Web UI:
+
+- **Collections page** → collection menu → **Export for gno.sh**
+- **Document view** → **Export for gno.sh**
+
+Upload the artifact at [gno.sh/studio](https://gno.sh/studio) and pick a visibility mode:
+
+| Mode                     | Use When                                            |
+| :----------------------- | :-------------------------------------------------- |
+| **Public**               | Open URL, indexable — talks, blog posts, portfolios |
+| **Secret link**          | Unguessable token, rotate / revoke / expire         |
+| **Invite-only**          | Private space for specific people                   |
+| **End-to-end encrypted** | WebCrypto bundle, passphrase decrypts in-browser    |
+
+**Reader experience**: editorial serif typography, drop caps, hanging punctuation, table of contents, keyboard shortcuts (`j/k`, `/`), scoped Pagefind-style search, and backlinks restricted to the published subset. Nothing leaks that you didn't publish.
+
+Republishing an artifact updates the same URL — no churn for your readers.
+
+> **Full story**: [gno.sh/publish](https://gno.sh/publish) · **Try it**: [gno.sh/studio](https://gno.sh/studio)
+
+---
+
 ## REST API
 
 Programmatic access to all GNO features via HTTP.

package/assets/skill/SKILL.md

@@ -22,6 +22,7 @@ Fast local semantic search. Index once, search instantly. No cloud, no API keys.
 - User wants to **tag, categorize, or filter** documents
 - User asks about **backlinks, wiki links, or related notes**
 - User wants to **visualize document connections** or see a **knowledge graph**
+- User wants to **export a note or collection for gno.sh publishing**
 
 ## Quick Start
 
@@ -44,6 +45,7 @@ gno search "your query"               # BM25 keyword search
 | **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                               |

package/assets/skill/cli-reference.md

@@ -494,6 +494,34 @@ gno serve [options]
 
 Features: Dashboard, search, browse collections, document viewer, AI Q&A with citations.
 
+## Publish
+
+### gno publish export
+
+Export a note or collection as a gno.sh publish artifact JSON.
+
+```bash
+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                                      |
+
+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
+```
+
+On success, upload the JSON file at `https://gno.sh/studio`.
+
 ## Skill Management
 
 ### gno skill install

package/package.json

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

@@ -88,6 +88,12 @@ export {
   type StatusResult,
   status,
 } from "./status";
+export {
+  formatPublishExport,
+  publishExport,
+  type PublishExportOptions,
+  type PublishExportResult,
+} from "./publish";
 export {
   formatUpdate,
   type UpdateOptions,

package/src/cli/commands/publish.ts

@@ -0,0 +1,140 @@
+/**
+ * gno publish export command.
+ *
+ * @module src/cli/commands/publish
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname } from "node:path";
+import { join } from "node:path";
+
+import type {
+  PublishArtifact,
+  PublishVisibility,
+} from "../../publish/artifact";
+
+import { derivePublishArtifactFilename, slugify } from "../../publish/artifact";
+import { exportPublishArtifact } from "../../publish/export-service";
+import { initStore } from "./shared";
+
+export interface PublishExportOptions {
+  configPath?: string;
+  json?: boolean;
+  out?: string;
+  slug?: string;
+  summary?: string;
+  title?: string;
+  visibility?: PublishVisibility;
+}
+
+export type PublishExportResult =
+  | {
+      success: true;
+      data: {
+        artifact: PublishArtifact;
+        outPath: string;
+        uploadUrl: string;
+      };
+    }
+  | { success: false; error: string; isValidation?: boolean };
+
+function formatExportDateStamp(isoTimestamp: string): string {
+  return isoTimestamp.slice(0, 10).replaceAll("-", "");
+}
+
+export function buildDefaultPublishExportPath(
+  artifact: PublishArtifact
+): string {
+  const fileName = derivePublishArtifactFilename(artifact).replace(
+    /\.json$/u,
+    ""
+  );
+  return join(
+    homedir(),
+    "Downloads",
+    `${fileName}-${formatExportDateStamp(artifact.exportedAt)}.json`
+  );
+}
+
+export async function publishExport(
+  target: string,
+  options: PublishExportOptions
+): Promise<PublishExportResult> {
+  const initResult = await initStore({
+    configPath: options.configPath,
+    syncConfig: false,
+  });
+  if (!initResult.ok) {
+    return { success: false, error: initResult.error };
+  }
+
+  const { collections, store } = initResult;
+
+  try {
+    const artifact = await exportPublishArtifact({
+      collections,
+      options: {
+        routeSlug: options.slug,
+        summary: options.summary,
+        title: options.title,
+        visibility: options.visibility,
+      },
+      store,
+      target,
+    });
+    const outPath =
+      options.out?.trim() || buildDefaultPublishExportPath(artifact);
+
+    await mkdir(dirname(outPath), { recursive: true });
+    await writeFile(outPath, JSON.stringify(artifact, null, 2));
+
+    return {
+      success: true,
+      data: {
+        artifact,
+        outPath,
+        uploadUrl: "https://gno.sh/studio",
+      },
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  } finally {
+    await store.close();
+  }
+}
+
+export function formatPublishExport(
+  result: PublishExportResult,
+  options: Pick<PublishExportOptions, "json">
+): string {
+  if (!result.success) {
+    if (options.json) {
+      return JSON.stringify({
+        error: {
+          code: result.isValidation ? "VALIDATION" : "RUNTIME",
+          message: result.error,
+        },
+      });
+    }
+    return `Error: ${result.error}`;
+  }
+
+  if (options.json) {
+    return JSON.stringify(result.data, null, 2);
+  }
+
+  const { artifact, outPath, uploadUrl } = result.data;
+  const space = artifact.spaces[0];
+
+  return [
+    `Exported ${space?.sourceType ?? "artifact"} to ${outPath}`,
+    `Route slug: ${space?.routeSlug ?? slugify(artifact.source)}`,
+    `Visibility: ${space?.visibility ?? "public"}`,
+    `Filename: ${derivePublishArtifactFilename(artifact)}`,
+    `Next: open ${uploadUrl} and drop ${outPath} into the upload zone.`,
+  ].join("\n");
+}

package/src/cli/options.ts

@@ -27,6 +27,7 @@ export const CMD = {
   multiGet: "multi-get",
   ls: "ls",
   status: "status",
+  publishExport: "publish.export",
   collectionList: "collection.list",
   contextList: "context.list",
   contextCheck: "context.check",
@@ -49,6 +50,7 @@ const FORMAT_SUPPORT: Record<CommandId, OutputFormat[]> = {
   [CMD.multiGet]: ["terminal", "json", "files", "md"],
   [CMD.ls]: ["terminal", "json", "files", "md"],
   [CMD.status]: ["terminal", "json"],
+  [CMD.publishExport]: ["terminal", "json"],
   [CMD.collectionList]: ["terminal", "json", "md"],
   [CMD.contextList]: ["terminal", "json", "md"],
   [CMD.contextCheck]: ["terminal", "json", "md"],

package/src/cli/program.ts

@@ -216,6 +216,7 @@ export function createProgram(): Command {
   wireSearchCommands(program);
   wireOnboardingCommands(program);
   wireManagementCommands(program);
+  wirePublishCommand(program);
   wireVecCommands(program);
   wireRetrievalCommands(program);
   wireTagsCommands(program);
@@ -1623,6 +1624,77 @@ function wireVecCommands(program: Command): void {
     });
 }
 
+function wirePublishCommand(program: Command): void {
+  const visibilityValues = [
+    "public",
+    "secret-link",
+    "invite-only",
+    "encrypted",
+  ] as const;
+  const publishCmd = program
+    .command("publish")
+    .description("Export publish artifacts for gno.sh");
+
+  publishCmd
+    .command("export <target>")
+    .description("Export a collection or document ref as a gno.sh artifact")
+    .option("--out <path>", "output artifact path")
+    .option(
+      "--visibility <mode>",
+      "visibility hint (public, secret-link, invite-only, encrypted)",
+      "public"
+    )
+    .option("--slug <slug>", "route slug override")
+    .option("--title <title>", "space title override")
+    .option("--summary <summary>", "space summary override")
+    .option("--json", "JSON output")
+    .action(async (target: string, cmdOpts: Record<string, unknown>) => {
+      const format = getFormat(cmdOpts);
+      assertFormatSupported(CMD.publishExport, format);
+      const globals = getGlobals();
+
+      const visibility = cmdOpts.visibility as string;
+      if (
+        !visibilityValues.includes(
+          visibility as (typeof visibilityValues)[number]
+        )
+      ) {
+        throw new CliError(
+          "VALIDATION",
+          `Invalid visibility: ${visibility}. Must be public, secret-link, invite-only, or encrypted.`
+        );
+      }
+
+      const { formatPublishExport, publishExport } =
+        await import("./commands/publish");
+      const result = await publishExport(target, {
+        configPath: globals.config,
+        json: format === "json",
+        out: typeof cmdOpts.out === "string" ? cmdOpts.out : undefined,
+        slug: cmdOpts.slug as string | undefined,
+        summary: cmdOpts.summary as string | undefined,
+        title: cmdOpts.title as string | undefined,
+        visibility: visibility as
+          | "encrypted"
+          | "invite-only"
+          | "public"
+          | "secret-link",
+      });
+
+      if (!result.success) {
+        throw new CliError(
+          result.isValidation ? "VALIDATION" : "RUNTIME",
+          result.error
+        );
+      }
+
+      await writeOutput(
+        formatPublishExport(result, { json: format === "json" }),
+        format
+      );
+    });
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Skill Commands (install, uninstall, show, paths)
 // ─────────────────────────────────────────────────────────────────────────────

package/src/publish/artifact.ts

@@ -0,0 +1,252 @@
+/**
+ * Publish artifact types and builders for gno.sh export.
+ *
+ * @module src/publish/artifact
+ */
+
+import type { DocumentRow, TagRow } from "../store/types";
+
+import { stripFrontmatter } from "../ingestion/frontmatter";
+
+export type PublishVisibility =
+  | "encrypted"
+  | "invite-only"
+  | "public"
+  | "secret-link";
+
+export interface PublishArtifactNote {
+  markdown: string;
+  metadata?: Record<string, string | string[]>;
+  slug: string;
+  summary: string;
+  title: string;
+}
+
+export interface PublishArtifactSpace {
+  homeNoteSlug?: string;
+  notes: PublishArtifactNote[];
+  routeSlug: string;
+  sourceType: "note" | "collection";
+  summary: string;
+  title: string;
+  visibility: PublishVisibility;
+}
+
+export interface PublishArtifact {
+  exportedAt: string;
+  source: string;
+  spaces: PublishArtifactSpace[];
+  version: 1;
+}
+
+export const PUBLISH_VISIBILITY_VALUES = [
+  "public",
+  "secret-link",
+  "invite-only",
+  "encrypted",
+] as const;
+
+export const MAX_PUBLISH_SLUG_LENGTH = 80;
+
+const ALLOWED_FRONTMATTER_METADATA_KEYS = new Set([
+  "audience",
+  "canonical",
+  "canonicalUrl",
+  "canonicalURL",
+  "coverAlt",
+  "coverImage",
+  "icon",
+  "image",
+  "layout",
+  "publishedAt",
+  "readingTime",
+  "series",
+  "seriesOrder",
+  "status",
+  "subtitle",
+  "theme",
+  "topic",
+  "topics",
+]);
+
+export const isPublishVisibility = (
+  value: unknown
+): value is PublishVisibility =>
+  typeof value === "string" &&
+  PUBLISH_VISIBILITY_VALUES.includes(value as PublishVisibility);
+
+export const slugify = (value: string) =>
+  value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/(^-|-$)/g, "");
+
+function toPublishSlugCandidate(value: string): string {
+  return slugify(value).slice(0, MAX_PUBLISH_SLUG_LENGTH).replace(/-+$/g, "");
+}
+
+export function derivePublishSlug(
+  candidates: Array<string>,
+  fallback = "untitled"
+): string {
+  for (const candidate of candidates) {
+    const slug = toPublishSlugCandidate(candidate);
+    if (slug.length > 0) {
+      return slug;
+    }
+  }
+
+  return fallback;
+}
+
+export const normalizePublishSlug = (value: string, fallback?: string) =>
+  derivePublishSlug([value], fallback);
+
+const basenameWithoutExt = (value: string) =>
+  value
+    .split("/")
+    .pop()
+    ?.replace(/\.[^.]+$/, "") ?? value;
+
+export const deriveExportedTitle = (
+  doc: Pick<DocumentRow, "relPath" | "title">
+) => doc.title?.trim() || basenameWithoutExt(doc.relPath);
+
+export const deriveExportedSlug = (
+  doc: Pick<DocumentRow, "relPath" | "title">
+) =>
+  derivePublishSlug([
+    deriveExportedTitle(doc),
+    doc.relPath.replace(/\.[^.]+$/, "").replaceAll("/", "-"),
+  ]);
+
+export const deriveExportedSummary = (
+  markdown: string,
+  metadata: Record<string, unknown>
+) => {
+  const metadataSummary =
+    typeof metadata.description === "string"
+      ? metadata.description
+      : typeof metadata.summary === "string"
+        ? metadata.summary
+        : null;
+  if (metadataSummary?.trim()) {
+    return metadataSummary.trim();
+  }
+
+  const plain = stripFrontmatter(markdown)
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(
+      (line) =>
+        line.length > 0 &&
+        !line.startsWith("#") &&
+        !line.startsWith("!") &&
+        !line.startsWith("```")
+    )
+    .join(" ")
+    .replace(/\s+/g, " ")
+    .trim();
+
+  return plain.slice(0, 200).trim();
+};
+
+export const buildExportedMetadata = (
+  doc: Pick<
+    DocumentRow,
+    | "author"
+    | "categories"
+    | "collection"
+    | "contentType"
+    | "frontmatterDate"
+    | "languageHint"
+    | "relPath"
+  >,
+  parsedFrontmatter: Record<string, unknown>,
+  tags: TagRow[]
+) => {
+  const metadata: Record<string, string | string[]> = {};
+
+  if (doc.author) {
+    metadata.author = doc.author;
+  }
+  if (doc.contentType) {
+    metadata.contentType = doc.contentType;
+  }
+  if (doc.languageHint) {
+    metadata.language = doc.languageHint;
+  }
+  if (doc.frontmatterDate) {
+    metadata.date = doc.frontmatterDate;
+  }
+  if (doc.categories?.length) {
+    metadata.categories = doc.categories;
+  }
+
+  const tagValues = tags.map((tag) => tag.tag);
+  if (tagValues.length) {
+    metadata.tags = tagValues;
+  }
+
+  metadata.collection = doc.collection;
+  metadata.sourceRelPath = doc.relPath;
+
+  for (const [key, value] of Object.entries(parsedFrontmatter)) {
+    if (
+      key === "tags" ||
+      key === "title" ||
+      key === "summary" ||
+      !ALLOWED_FRONTMATTER_METADATA_KEYS.has(key)
+    ) {
+      continue;
+    }
+    if (typeof value === "string" && value.trim()) {
+      metadata[key] = value.trim();
+      continue;
+    }
+    if (Array.isArray(value)) {
+      const cleaned = value
+        .filter((entry): entry is string => typeof entry === "string")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+      if (cleaned.length > 0) {
+        metadata[key] = cleaned;
+      }
+    }
+  }
+
+  return metadata;
+};
+
+export const buildPublishArtifact = (input: {
+  homeNoteSlug?: string;
+  notes: PublishArtifactNote[];
+  routeSlug: string;
+  source: string;
+  sourceType: "note" | "collection";
+  summary: string;
+  title: string;
+  visibility: PublishVisibility;
+}) => ({
+  exportedAt: new Date().toISOString(),
+  source: input.source,
+  spaces: [
+    {
+      homeNoteSlug: input.homeNoteSlug,
+      notes: input.notes,
+      routeSlug: input.routeSlug,
+      sourceType: input.sourceType,
+      summary: input.summary,
+      title: input.title,
+      visibility: input.visibility,
+    },
+  ],
+  version: 1 as const,
+});
+
+export const derivePublishArtifactFilename = (artifact: PublishArtifact) => {
+  const routeSlug =
+    artifact.spaces[0]?.routeSlug.trim() ||
+    normalizePublishSlug(artifact.source, "publish-artifact");
+  return `${routeSlug || "publish-artifact"}.json`;
+};