@gmickel/gno 0.41.0 → 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
@@ -122,6 +128,15 @@ gno collection clear-embeddings my-collection --all
 gno embed my-collection
 ```
 
+If a re-embed run still reports failures, rerun with:
+
+```bash
+gno --verbose embed --force
+```
+
+Recent releases now print sample embedding errors and a concrete retry hint when
+batch recovery cannot fully recover on its own.
+
 Model guides:
 
 - [Code Embeddings](./docs/guides/code-embeddings.md)
@@ -401,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.
@@ -581,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.0",
+  "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/embed.ts

@@ -71,6 +71,9 @@ export type EmbedResult =
       duration: number;
       model: string;
       searchAvailable: boolean;
+      errorSamples?: string[];
+      suggestion?: string;
+      syncError?: string;
     }
   | { success: false; error: string };
 
@@ -87,6 +90,30 @@ function formatDuration(seconds: number): string {
   return `${mins}m ${secs.toFixed(0)}s`;
 }
 
+function formatLlmFailure(
+  error: { message: string; cause?: unknown } | undefined
+): string {
+  if (!error) {
+    return "Unknown embedding failure";
+  }
+  const cause =
+    error.cause &&
+    typeof error.cause === "object" &&
+    "message" in error.cause &&
+    typeof error.cause.message === "string"
+      ? error.cause.message
+      : typeof error.cause === "string"
+        ? error.cause
+        : "";
+  return cause && cause !== error.message
+    ? `${error.message} - ${cause}`
+    : error.message;
+}
+
+function isDisposedBatchError(message: string): boolean {
+  return message.toLowerCase().includes("object is disposed");
+}
+
 async function checkVecAvailable(
   db: import("bun:sqlite").Database
 ): Promise<boolean> {
@@ -111,10 +138,20 @@ interface BatchContext {
   showProgress: boolean;
   totalToEmbed: number;
   verbose: boolean;
+  recreateEmbedPort?: () => Promise<
+    { ok: true; value: EmbeddingPort } | { ok: false; error: string }
+  >;
 }
 
 type BatchResult =
-  | { ok: true; embedded: number; errors: number; duration: number }
+  | {
+      ok: true;
+      embedded: number;
+      errors: number;
+      duration: number;
+      errorSamples: string[];
+      suggestion?: string;
+    }
   | { ok: false; error: string };
 
 interface Cursor {
@@ -126,8 +163,21 @@ async function processBatches(ctx: BatchContext): Promise<BatchResult> {
   const startTime = Date.now();
   let embedded = 0;
   let errors = 0;
+  const errorSamples: string[] = [];
+  let suggestion: string | undefined;
   let cursor: Cursor | undefined;
 
+  const pushErrorSamples = (samples: string[]): void => {
+    for (const sample of samples) {
+      if (errorSamples.length >= 5) {
+        break;
+      }
+      if (!errorSamples.includes(sample)) {
+        errorSamples.push(sample);
+      }
+    }
+  };
+
   while (embedded + errors < ctx.totalToEmbed) {
     // Get next batch using seek pagination (cursor-based)
     const batchResult = ctx.force
@@ -161,6 +211,89 @@ async function processBatches(ctx: BatchContext): Promise<BatchResult> {
       )
     );
     if (!batchEmbedResult.ok) {
+      const formattedError = formatLlmFailure(batchEmbedResult.error);
+      if (ctx.recreateEmbedPort && isDisposedBatchError(formattedError)) {
+        if (ctx.verbose) {
+          process.stderr.write(
+            "\n[embed] Embedding port disposed; recreating model/contexts and retrying batch once\n"
+          );
+        }
+        const recreated = await ctx.recreateEmbedPort();
+        if (recreated.ok) {
+          ctx.embedPort = recreated.value;
+          const retryResult = await embedTextsWithRecovery(
+            ctx.embedPort,
+            batch.map((b) =>
+              formatDocForEmbedding(b.text, b.title ?? undefined, ctx.modelUri)
+            )
+          );
+          if (retryResult.ok) {
+            if (ctx.verbose) {
+              process.stderr.write(
+                "\n[embed] Retry after port reset succeeded\n"
+              );
+            }
+            pushErrorSamples(retryResult.value.failureSamples);
+            suggestion ||= retryResult.value.retrySuggestion;
+
+            const retryVectors: VectorRow[] = [];
+            for (const [idx, item] of batch.entries()) {
+              const embedding = retryResult.value.vectors[idx];
+              if (!embedding) {
+                errors += 1;
+                continue;
+              }
+              retryVectors.push({
+                mirrorHash: item.mirrorHash,
+                seq: item.seq,
+                model: ctx.modelUri,
+                embedding: new Float32Array(embedding),
+              });
+            }
+
+            if (retryVectors.length === 0) {
+              if (ctx.verbose) {
+                process.stderr.write(
+                  "\n[embed] No recoverable embeddings in retry batch\n"
+                );
+              }
+              continue;
+            }
+
+            const retryStoreResult =
+              await ctx.vectorIndex.upsertVectors(retryVectors);
+            if (!retryStoreResult.ok) {
+              if (ctx.verbose) {
+                process.stderr.write(
+                  `\n[embed] Store failed: ${retryStoreResult.error.message}\n`
+                );
+              }
+              pushErrorSamples([retryStoreResult.error.message]);
+              suggestion ??=
+                "Store write failed. Rerun `gno embed` once more; if it repeats, run `gno doctor` and `gno vec sync`.";
+              errors += retryVectors.length;
+              continue;
+            }
+
+            embedded += retryVectors.length;
+            if (ctx.showProgress) {
+              const embeddedDisplay = Math.min(embedded, ctx.totalToEmbed);
+              const completed = Math.min(embedded + errors, ctx.totalToEmbed);
+              const pct = (completed / ctx.totalToEmbed) * 100;
+              const elapsed = (Date.now() - startTime) / 1000;
+              const rate = embedded / Math.max(elapsed, 0.001);
+              const eta =
+                Math.max(0, ctx.totalToEmbed - completed) /
+                Math.max(rate, 0.001);
+              process.stdout.write(
+                `\rEmbedding: ${embeddedDisplay.toLocaleString()}/${ctx.totalToEmbed.toLocaleString()} (${pct.toFixed(1)}%) | ${rate.toFixed(1)} chunks/s | ETA ${formatDuration(eta)}`
+              );
+            }
+            continue;
+          }
+        }
+      }
+
       if (ctx.verbose) {
         const err = batchEmbedResult.error;
         const cause = err.cause;
@@ -178,6 +311,9 @@ async function processBatches(ctx: BatchContext): Promise<BatchResult> {
           `\n[embed] Batch failed (${batch.length} chunks: ${titles}${batch.length > 3 ? "..." : ""}): ${err.message}${causeMsg ? ` - ${causeMsg}` : ""}\n`
         );
       }
+      pushErrorSamples([formattedError]);
+      suggestion =
+        "Try rerunning the same command. If failures persist, rerun with `gno --verbose embed --batch-size 1` to isolate failing chunks.";
       errors += batch.length;
       continue;
     }
@@ -191,6 +327,13 @@ async function processBatches(ctx: BatchContext): Promise<BatchResult> {
         `\n[embed] Batch fallback (${batch.length} chunks: ${titles}${batch.length > 3 ? "..." : ""}): ${batchEmbedResult.value.batchError ?? "unknown batch error"}\n`
       );
     }
+    pushErrorSamples(batchEmbedResult.value.failureSamples);
+    suggestion ||= batchEmbedResult.value.retrySuggestion;
+    if (ctx.verbose && batchEmbedResult.value.failureSamples.length > 0) {
+      for (const sample of batchEmbedResult.value.failureSamples) {
+        process.stderr.write(`\n[embed] Sample failure: ${sample}\n`);
+      }
+    }
 
     const vectors: VectorRow[] = [];
     for (const [idx, item] of batch.entries()) {
@@ -221,6 +364,9 @@ async function processBatches(ctx: BatchContext): Promise<BatchResult> {
           `\n[embed] Store failed: ${storeResult.error.message}\n`
         );
       }
+      pushErrorSamples([storeResult.error.message]);
+      suggestion ??=
+        "Store write failed. Rerun `gno embed` once more; if it repeats, run `gno doctor` and `gno vec sync`.";
       errors += vectors.length;
       continue;
     }
@@ -229,13 +375,15 @@ async function processBatches(ctx: BatchContext): Promise<BatchResult> {
 
     // Progress output
     if (ctx.showProgress) {
-      const pct = ((embedded + errors) / ctx.totalToEmbed) * 100;
+      const embeddedDisplay = Math.min(embedded, ctx.totalToEmbed);
+      const completed = Math.min(embedded + errors, ctx.totalToEmbed);
+      const pct = (completed / ctx.totalToEmbed) * 100;
       const elapsed = (Date.now() - startTime) / 1000;
       const rate = embedded / Math.max(elapsed, 0.001);
       const eta =
-        (ctx.totalToEmbed - embedded - errors) / Math.max(rate, 0.001);
+        Math.max(0, ctx.totalToEmbed - completed) / Math.max(rate, 0.001);
       process.stdout.write(
-        `\rEmbedding: ${embedded.toLocaleString()}/${ctx.totalToEmbed.toLocaleString()} (${pct.toFixed(1)}%) | ${rate.toFixed(1)} chunks/s | ETA ${formatDuration(eta)}`
+        `\rEmbedding: ${embeddedDisplay.toLocaleString()}/${ctx.totalToEmbed.toLocaleString()} (${pct.toFixed(1)}%) | ${rate.toFixed(1)} chunks/s | ETA ${formatDuration(eta)}`
       );
     }
   }
@@ -249,6 +397,8 @@ async function processBatches(ctx: BatchContext): Promise<BatchResult> {
     embedded,
     errors,
     duration: (Date.now() - startTime) / 1000,
+    errorSamples,
+    suggestion,
   };
 }
 
@@ -354,6 +504,7 @@ export async function embed(options: EmbedOptions = {}): Promise<EmbedResult> {
         duration: 0,
         model: modelUri,
         searchAvailable: vecAvailable,
+        errorSamples: [],
       };
     }
 
@@ -366,6 +517,7 @@ export async function embed(options: EmbedOptions = {}): Promise<EmbedResult> {
         duration: 0,
         model: modelUri,
         searchAvailable: vecAvailable,
+        errorSamples: [],
       };
     }
 
@@ -382,6 +534,27 @@ export async function embed(options: EmbedOptions = {}): Promise<EmbedResult> {
       : undefined;
 
     const llm = new LlmAdapter(config);
+    const recreateEmbedPort = async () => {
+      if (embedPort) {
+        await embedPort.dispose();
+      }
+      await llm.getManager().dispose(modelUri);
+      const recreated = await llm.createEmbeddingPort(modelUri, {
+        policy,
+        onProgress: downloadProgress
+          ? (progress) => downloadProgress("embed", progress)
+          : undefined,
+      });
+      if (!recreated.ok) {
+        return { ok: false as const, error: recreated.error.message };
+      }
+      const initResult = await recreated.value.init();
+      if (!initResult.ok) {
+        await recreated.value.dispose();
+        return { ok: false as const, error: initResult.error.message };
+      }
+      return { ok: true as const, value: recreated.value };
+    };
     const embedResult = await llm.createEmbeddingPort(modelUri, {
       policy,
       onProgress: downloadProgress
@@ -428,6 +601,7 @@ export async function embed(options: EmbedOptions = {}): Promise<EmbedResult> {
       showProgress: !options.json,
       totalToEmbed,
       verbose: options.verbose ?? false,
+      recreateEmbedPort,
     });
 
     if (!result.ok) {
@@ -447,10 +621,27 @@ export async function embed(options: EmbedOptions = {}): Promise<EmbedResult> {
           }
         }
         vectorIndex.vecDirty = false;
-      } else if (!options.json) {
-        process.stdout.write(
-          `\n[vec] Sync failed: ${syncResult.error.message}\n`
-        );
+      } else {
+        if (!options.json) {
+          process.stdout.write(
+            `\n[vec] Sync failed: ${syncResult.error.message}\n`
+          );
+        }
+        return {
+          success: true,
+          embedded: result.embedded,
+          errors: result.errors,
+          duration: result.duration,
+          model: modelUri,
+          searchAvailable: vectorIndex.searchAvailable,
+          errorSamples: [
+            ...result.errorSamples,
+            syncResult.error.message,
+          ].slice(0, 5),
+          suggestion:
+            "Vector index sync failed after embedding. Rerun `gno embed` once more. If it repeats, run `gno vec sync`.",
+          syncError: syncResult.error.message,
+        };
       }
     }
 
@@ -461,6 +652,8 @@ export async function embed(options: EmbedOptions = {}): Promise<EmbedResult> {
       duration: result.duration,
       model: modelUri,
       searchAvailable: vectorIndex.searchAvailable,
+      errorSamples: result.errorSamples,
+      suggestion: result.suggestion,
     };
   } finally {
     if (embedPort) {
@@ -585,6 +778,9 @@ export function formatEmbed(
         duration: result.duration,
         model: result.model,
         searchAvailable: result.searchAvailable,
+        errorSamples: result.errorSamples ?? [],
+        suggestion: result.suggestion,
+        syncError: result.syncError,
       },
       null,
       2
@@ -606,6 +802,14 @@ export function formatEmbed(
 
   if (result.errors > 0) {
     lines.push(`${result.errors} chunks failed to embed.`);
+    if ((result.errorSamples?.length ?? 0) > 0) {
+      for (const sample of result.errorSamples ?? []) {
+        lines.push(`Sample error: ${sample}`);
+      }
+    }
+    if (result.suggestion) {
+      lines.push(`Hint: ${result.suggestion}`);
+    }
   }
 
   if (!result.searchAvailable) {
@@ -614,5 +818,9 @@ export function formatEmbed(
     );
   }
 
+  if (result.syncError) {
+    lines.push(`Vec sync error: ${result.syncError}`);
+  }
+
   return lines.join("\n");
 }

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