@llamaventures/cli 1.4.3 → 1.5.0

package/AGENT_BRIEFING.md

@@ -33,6 +33,8 @@ Conversation produces value → that value flows somewhere. This is not optional
 |---|---|---|
 | Deal metadata (status, stage, valuation, founders, notes, etc.) | Pipeline (Postgres) | `llama deal create` / `llama deal update` |
 | Brief blocks (text / link / embed / callout) | Pipeline | `llama brief add-text` / `add-link` / `add-callout` |
+| **HTML artifact, internal — IC report, dashboard, market map, 2×2, any hand-authored page** | **Llama Command native** (Postgres + sandboxed iframe at `/deals/<id>/browse/<slug>`) | Default path when the user says "deploy to llama", "deploy to llama command", "部署到 llama command", "put this HTML on the deal page", "在 deal 里看这个". **You MUST declare intent — "new artifact" vs "update existing":**<br><br>**New artifact:** `llama html upload <dealId> --new --title "<artifact name>" --file <path>` (CLI slugifies the title; pass `--doc <slug>` to override).<br>**Update existing:** `llama html upload <dealId> --doc <slug> --file <path>` (slug must already exist — run `llama html docs <dealId>` first to see what's there).<br><br>The bare form `llama html upload <id> --file <path>` REFUSES if `main` already has content. Do NOT default to Netlify for internal pages. |
+| HTML artifact, external — founder-facing share link | Netlify | Only when the user explicitly says "share link", "give it to the founder", "publish publicly". Use the `netlify-access-guard` workflow (server-side password + edge 401 verification). |
 | Insights, decisions, framework improvements | Wiki | `llama wiki save` (with attribution — see below) |
 | Large files (deck / PDF / transcript) | Drive deal folder | the deal's `folder_url` (from `llama deal show`) → upload via your filesystem / Drive tool |
 | Cross-team mentions | Inbox + email | `llama post <dealId> "@<teammate> ..."` — server fires email + UI badge to the recipient |
@@ -106,6 +108,34 @@ llama brief add-text <dealId> --heading "..." --body "..."
 llama brief add-link <dealId> --url "..." --label "..."
 llama brief add-callout <dealId> --tone insight|warning|info|success --heading "..." --body "..."
 
+# Deal HTML — native deploy to /deals/<id>/browse/<slug>
+# Default path when user says "deploy to llama / 部署到 llama command / put this HTML on the deal page".
+# Each deal can host many slug-scoped artifacts. ALWAYS declare intent: new vs update.
+
+llama html docs <dealId>                                                 # list slugs currently on this deal
+llama html docs create <dealId> <slug> [--title "..."]                   # pre-create a slot (optional; upload --new also creates)
+llama html docs archive <dealId> <slug>                                  # soft-archive a doc
+
+# Add a NEW artifact (slug must NOT already exist):
+llama html upload <dealId> --new --title "Consumer-Facing Thesis" --file ./thesis.html
+llama html upload <dealId> --new --doc thesis --title "Consumer-Facing Thesis" --file ./thesis.html
+
+# Update an EXISTING artifact (slug must already exist):
+llama html upload <dealId> --doc <slug> --file ./report.html [--assets ./assets]
+
+# Common helpers (all accept --doc <slug>; default 'main'):
+llama html show <dealId> [--doc <slug>] [--out path] [--json]            # current HTML → stdout
+llama html versions <dealId> [--doc <slug>]                              # version history (incl. soft-deleted)
+llama html restore <dealId> <version> [--doc <slug>]                     # promote old version to latest
+llama html reset <dealId> [--doc <slug>]                                 # soft-delete latest (browse reverts to empty)
+
+# Safety contract (since 1.5.0):
+#  - Bare `llama html upload <id> --file X` REFUSES if 'main' already has content.
+#    The error names the existing artifact and suggests --doc main / --new --title "...".
+#  - --slug is silently accepted as an alias for --doc (agent-confusion mitigation).
+#  - Unknown flags print a warning to stderr suggesting a likely match.
+#  - JSON output gains `mode: 'created' | 'updated'` so callers can branch.
+
 # Wiki (knowledge base)
 llama wiki search "<query>"
 llama wiki save <slug> --title "..." --content "..."

package/bin/llama-mcp.mjs

@@ -661,6 +661,266 @@ server.registerTool(
     })
 );
 
+// ============================================================
+// Deal page HTML — hand-authored sandboxed page per deal
+// ============================================================
+//
+// Each deal has its own /deals/<id>/browse page that renders a
+// hand-authored HTML in a sandboxed iframe (allow-scripts, no
+// same-origin). Uploads from any caller (web UI, CLI, agent, MCP)
+// create a new monotonic version + trigger SSE push so any open
+// viewer refreshes in real time. Old versions are soft-deleted on
+// replace and can be restored.
+
+// All html_* tools take an optional documentSlug param. Default 'main'.
+// Each deal can hold multiple named documents (different HTMLs); use
+// html_docs_list to discover slugs.
+function htmlUrl(dealId, slug) {
+  return `/api/deals/${encodeURIComponent(dealId)}/documents/${encodeURIComponent(slug ?? "main")}/html`;
+}
+
+server.registerTool(
+  "html_show",
+  {
+    description:
+      "Read the current hand-authored HTML 'deal page' for a deal. " +
+      "Returns {empty: true} if no one has uploaded HTML yet, or " +
+      "{empty: false, version, html, bytes, uploaded_by, source, " +
+      "created_at}. The HTML can be 5-500KB — be deliberate about " +
+      "including the body in your reply. Use html_versions if you " +
+      "just want the version list without the body. Each deal can " +
+      "have multiple named docs — pass documentSlug to target a " +
+      "non-'main' one (use html_docs_list to discover them).",
+    inputSchema: {
+      dealId: z.string().describe("deal uuid"),
+      documentSlug: z
+        .string()
+        .optional()
+        .describe("default: 'main'. Use html_docs_list to discover slugs."),
+    },
+  },
+  async ({ dealId, documentSlug }) =>
+    callApi("GET", htmlUrl(dealId, documentSlug))
+);
+
+server.registerTool(
+  "html_upload",
+  {
+    description:
+      "Upload (PUT) a new HTML version for a deal's /browse page. " +
+      "Creates a NEW version row — the previous version is retained " +
+      "and restorable. Triggers SSE push so any open viewer auto- " +
+      "refreshes. Constraints: HTML body MUST start with " +
+      "<!doctype html> or <html (case-insensitive); max 5 MB. ALWAYS " +
+      "call html_show first if anything exists — replace only the " +
+      "relevant section, don't lose unrelated content. Source defaults " +
+      "to 'agent' for MCP-originated uploads. Pass documentSlug to " +
+      "target a non-'main' doc — auto-creates the doc if it doesn't exist.",
+    inputSchema: {
+      dealId: z.string().describe("deal uuid"),
+      html: z.string().describe("complete HTML document"),
+      documentSlug: z
+        .string()
+        .optional()
+        .describe("default: 'main'"),
+      source: z
+        .enum(["web", "cli", "agent"])
+        .optional()
+        .describe("default: agent"),
+    },
+  },
+  async ({ dealId, html, documentSlug, source }) =>
+    callApi("PUT", htmlUrl(dealId, documentSlug), {
+      html,
+      source: source ?? "agent",
+    })
+);
+
+server.registerTool(
+  "html_versions",
+  {
+    description:
+      "List version history for a deal's /browse page HTML. Returns " +
+      "an array of {version, bytes, uploaded_by, source, created_at, " +
+      "deleted_at} — newest first, including soft-deleted versions. " +
+      "Use to find a target version for html_restore.",
+    inputSchema: {
+      dealId: z.string().describe("deal uuid"),
+      documentSlug: z.string().optional().describe("default: 'main'"),
+    },
+  },
+  async ({ dealId, documentSlug }) =>
+    callApi("GET", `${htmlUrl(dealId, documentSlug)}/history`)
+);
+
+server.registerTool(
+  "html_restore",
+  {
+    description:
+      "Restore an old HTML version by copying it forward as a new " +
+      "version (so the latest pointer moves to the restored content). " +
+      "Use html_versions first to discover the version number. " +
+      "Triggers SSE push.",
+    inputSchema: {
+      dealId: z.string().describe("deal uuid"),
+      version: z.number().int().positive().describe("version to restore"),
+      documentSlug: z.string().optional().describe("default: 'main'"),
+    },
+  },
+  async ({ dealId, version, documentSlug }) =>
+    callApi("POST", `${htmlUrl(dealId, documentSlug)}/restore/${version}`)
+);
+
+server.registerTool(
+  "html_docs_list",
+  {
+    description:
+      "List all documents (HTML 'pages') on a deal. Each deal can " +
+      "hold multiple — like a folder of files. Returns an array of " +
+      "{slug, title, preview_url, created_by, latest_version, " +
+      "latest_bytes, latest_uploaded_by, latest_updated_at}. The " +
+      "'main' slug is the default doc; non-main slugs are explicit.",
+    inputSchema: {
+      dealId: z.string().describe("deal uuid"),
+    },
+  },
+  async ({ dealId }) =>
+    callApi("GET", `/api/deals/${encodeURIComponent(dealId)}/documents`)
+);
+
+server.registerTool(
+  "html_docs_create",
+  {
+    description:
+      "Create a NEW named document slot on a deal (metadata only — " +
+      "upload HTML separately via html_upload with the same slug). " +
+      "Slug must match /^[a-z0-9][a-z0-9_-]{0,63}$/ — lowercase alnum + " +
+      "hyphen/underscore. Examples: 'ic-onepager', 'founder-brief', " +
+      "'market-map'. Title is for display; defaults to the slug.",
+    inputSchema: {
+      dealId: z.string().describe("deal uuid"),
+      slug: z.string().describe("URL-safe id, e.g. 'ic-onepager'"),
+      title: z.string().optional().describe("display title; defaults to slug"),
+    },
+  },
+  async ({ dealId, slug, title }) =>
+    callApi("POST", `/api/deals/${encodeURIComponent(dealId)}/documents`, {
+      slug,
+      title: title ?? slug,
+    })
+);
+
+server.registerTool(
+  "html_docs_archive",
+  {
+    description:
+      "Archive a non-'main' doc — hides it from the selection page. " +
+      "HTML/asset versions are retained and the doc can be 'un-archived' " +
+      "later (currently via direct DB or by ensureDealDocument). The " +
+      "'main' doc cannot be archived (it's the default slot).",
+    inputSchema: {
+      dealId: z.string().describe("deal uuid"),
+      slug: z.string().describe("slug to archive (must not be 'main')"),
+    },
+  },
+  async ({ dealId, slug }) =>
+    callApi(
+      "DELETE",
+      `/api/deals/${encodeURIComponent(dealId)}/documents/${encodeURIComponent(slug)}`
+    )
+);
+
+server.registerTool(
+  "html_upload_bundle",
+  {
+    description:
+      "Upload HTML + binary assets as one atomic version. Use this " +
+      "INSTEAD of html_upload when the HTML references local images / " +
+      "fonts / CSS files via relative src=/href= attributes (typical " +
+      "of 'Save Page As Complete' exports). The server stores HTML + " +
+      "each asset as one transactional bundle (deal_browse_assets " +
+      "table), rewrites the HTML refs to version-pinned URLs at " +
+      "/api/deals/<id>/asset/<path>?v=N, and triggers SSE push. " +
+      "Constraints: HTML <= 5 MB; each asset <= 50 MB; total bundle " +
+      "<= 100 MB. Asset paths must match the relative refs in the HTML " +
+      "(no leading './', no '..' segments).",
+    inputSchema: {
+      dealId: z.string().describe("deal uuid"),
+      html: z.string().describe("complete HTML document"),
+      assets: z
+        .array(
+          z.object({
+            path: z
+              .string()
+              .describe(
+                "relative path matching the HTML's src/href ref " +
+                  "(e.g. 'images/cover.png' or 'Foo_files/img.jpg')",
+              ),
+            contentType: z
+              .string()
+              .describe("MIME type, e.g. 'image/jpeg', 'font/woff2'"),
+            base64: z
+              .string()
+              .describe("base64-encoded file bytes (NO data:URI prefix)"),
+          }),
+        )
+        .min(1)
+        .describe("at least one asset (use html_upload if no assets)"),
+      documentSlug: z
+        .string()
+        .optional()
+        .describe("default: 'main'"),
+      source: z
+        .enum(["web", "cli", "agent"])
+        .optional()
+        .describe("default: agent"),
+    },
+  },
+  async ({ dealId, html, assets, documentSlug, source }) => {
+    const form = new FormData();
+    form.append("html", html);
+    form.append("source", source ?? "agent");
+    for (const a of assets) {
+      const bytes = Buffer.from(a.base64, "base64");
+      form.append(
+        `asset:${a.path}`,
+        new Blob([bytes], { type: a.contentType || "application/octet-stream" }),
+        a.path,
+      );
+    }
+    const headers = await getAuthHeaders();
+    const res = await fetch(`${getBaseUrl()}${htmlUrl(dealId, documentSlug)}`, {
+      method: "PUT",
+      headers, // let fetch set multipart Content-Type with boundary
+      body: form,
+    });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw new Error(
+        `HTTP ${res.status}: ${body?.error || JSON.stringify(body).slice(0, 300)}`,
+      );
+    }
+    return body;
+  },
+);
+
+server.registerTool(
+  "html_reset",
+  {
+    description:
+      "Soft-delete the latest HTML version for a deal. The /browse " +
+      "page reverts to its empty state (drop / paste / CLI / agent " +
+      "invitation). Old versions are retained and restorable via " +
+      "html_restore.",
+    inputSchema: {
+      dealId: z.string().describe("deal uuid"),
+      documentSlug: z.string().optional().describe("default: 'main'"),
+    },
+  },
+  async ({ dealId, documentSlug }) =>
+    callApi("DELETE", htmlUrl(dealId, documentSlug))
+);
+
 // ============================================================
 // Prompts
 // ============================================================

package/bin/llama.mjs

@@ -31,7 +31,7 @@ import {
 import { LLAMA_CLI_CLIENT_ID, pkceLoopbackFlow, revokeToken as revokeOAuthToken } from "../lib/oauth-flow.mjs";
 import { deleteBundle, detectBackend, readBundle, writeBundle } from "../lib/oauth-storage.mjs";
 
-function parseFlags(args) {
+function parseFlags(args, knownFlags = null) {
   const flags = {};
   const positional = [];
   for (let i = 0; i < args.length; i++) {
@@ -49,9 +49,82 @@ function parseFlags(args) {
       positional.push(arg);
     }
   }
+  // Opt-in unknown-flag warning. Handlers that pass a `knownFlags` array
+  // get a stderr nudge when they see typos like `--slug` for `--doc`.
+  // Don't reject — agents wrap legacy options, breaking them silently is
+  // worse than a one-line warning.
+  if (Array.isArray(knownFlags)) {
+    const known = new Set(knownFlags);
+    for (const key of Object.keys(flags)) {
+      if (!known.has(key)) {
+        const suggestion = closestKnownFlag(key, knownFlags);
+        process.stderr.write(
+          suggestion
+            ? `warning: unknown flag --${key} (did you mean --${suggestion}?)\n`
+            : `warning: unknown flag --${key}\n`,
+        );
+      }
+    }
+  }
   return { flags, positional };
 }
 
+function closestKnownFlag(input, candidates) {
+  let best = null;
+  let bestScore = Infinity;
+  for (const c of candidates) {
+    const d = levenshtein(input, c);
+    const tolerance = Math.max(2, Math.floor(c.length / 3));
+    if (d < bestScore && d <= tolerance) {
+      best = c;
+      bestScore = d;
+    }
+  }
+  return best;
+}
+
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  const dp = Array(n + 1).fill(0).map((_, i) => i);
+  for (let i = 1; i <= m; i++) {
+    let prev = dp[0];
+    dp[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const tmp = dp[j];
+      dp[j] = a[i - 1] === b[j - 1]
+        ? prev
+        : 1 + Math.min(prev, dp[j - 1], dp[j]);
+      prev = tmp;
+    }
+  }
+  return dp[n];
+}
+
+// Slug shape used by deal_documents.slug (matches server-side SLUG_RE).
+function isValidDocSlug(s) {
+  return typeof s === "string" && /^[a-z0-9][a-z0-9_-]{0,63}$/.test(s);
+}
+
+// Best-effort title → slug. Strips diacritics, lowercases, collapses
+// non-alnum to single hyphens, trims, caps at 64. Returns null if the
+// result wouldn't pass `isValidDocSlug` (caller must then require --doc).
+function slugifyTitle(title) {
+  if (typeof title !== "string") return null;
+  const slug = title
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[̀-ͯ]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 64);
+  if (!slug || !/^[a-z0-9]/.test(slug)) return null;
+  return slug;
+}
+
 // Client-side fuzzy match — used as a fallback when the server hasn't yet
 // shipped the search/filter API (Fix B, 2026-04-25). Once the server
 // returns the `{deals,total,limit,offset}` envelope, this path is never
@@ -262,6 +335,36 @@ Memo (long-form HTML investment memo — Memo tab in the UI):
   llama memo save <dealId> --file <path>                     # paste a hand-written HTML as manual override
   llama memo reset <dealId> [--all]                          # default drops manual override; --all drops every version
 
+Deal page HTML (hand-authored sandboxed pages on /deals/<id>/browse/<slug>):
+  Each deal can host many HTML artifacts (IC report, dashboard, market map, …).
+  Each one has a stable slug. UPLOAD must declare intent — update an existing
+  artifact or add a new one — to avoid silent overwrites.
+
+  List existing artifacts:
+    llama html docs <dealId>                                  # who-has-what
+    llama html docs create <dealId> <slug> [--title "..."]    # pre-create a slot
+    llama html docs archive <dealId> <slug>                   # soft-archive (browse hides)
+
+  Update an EXISTING artifact (slug must exist):
+    llama html upload <dealId> --doc <slug> --file <path> [--assets DIR]
+
+  Add a NEW artifact (slug must NOT already exist):
+    llama html upload <dealId> --new --title "..." --file <path> [--doc <slug>] [--assets DIR]
+      (omit --doc → CLI slugifies the title; appends -2 / -3 on collision)
+
+  Default (no --doc, no --new) targets slug 'main' but REFUSES if 'main'
+  already has content — pass --doc main or --new --title "..." explicitly.
+
+  llama html show <dealId> [--doc <slug>] [--out <path>] [--json]   # default: current html → stdout
+  llama html versions <dealId> [--doc <slug>]                       # list version history
+  llama html restore <dealId> <version> [--doc <slug>]              # promote an old version to new latest
+  llama html reset <dealId> [--doc <slug>]                          # soft-delete latest; /browse reverts to empty
+
+  Caps: HTML 5 MB, each asset 50 MB, total bundle 100 MB. Every write
+  triggers SSE push — any browser viewing /deals/<id>/browse refreshes
+  automatically. Same write path as the in-app deal agent's
+  update_deal_browse_html tool and the MCP html_upload_bundle tool.
+
 Admin (system admin only — server returns 403 for non-admin tokens):
   llama admin auth-events  [--kind X] [--actor email] [--subject email] [--since 24h|7d|30d|<ISO>] [--limit 100]
   llama admin deal-events  [--kind X] [--actor email] [--deal <uuid>] [--since 24h] [--limit 100]
@@ -1221,8 +1324,8 @@ https://command.llamaventures.vc/settings/tokens, run
   // Hits /api/wiki/<slug> directly. Earlier versions did a fuzzy
   // /api/wiki/search call and filtered for an exact slug match — that
   // missed any article whose slug-as-string didn't appear in title or
-  // content (e.g. "jack-feng" search vs "Jack Feng" content), so a real
-  // article would print as "not found" even though it existed.
+  // content (e.g. a slug like "foo-bar" against an article titled "Foo Bar"),
+  // so a real article would print as "not found" even though it existed.
   if (area === "wiki" && action === "read") {
     const { flags, positional } = parseFlags(rest);
     const slug = positional[0];
@@ -1792,6 +1895,540 @@ https://command.llamaventures.vc/settings/tokens, run
     );
   }
 
+  // ============================================================
+  // `llama html` family — per-deal hand-authored HTML "deal page"
+  // ============================================================
+  //
+  // Each deal can have its own HTML browse view (sandboxed iframe).
+  // Upload via this CLI, or directly via the web UI's drag-drop / paste,
+  // or by the in-app deal agent via the update_deal_browse_html tool.
+  // Every upload creates a new monotonic version; old versions are
+  // soft-deleted on replace and can be restored.
+  //
+  //   llama html show <dealId> [--out PATH] [--json]
+  //   llama html upload <dealId> --file PATH [--source cli|web|agent]
+  //   llama html versions <dealId>
+  //   llama html restore <dealId> <version>
+  //   llama html reset <dealId>
+  if (area === "html") {
+    const sub = action;
+
+    // --doc <slug> selects which named document on the deal (default 'main').
+    // Slugs match /^[a-z0-9][a-z0-9_-]{0,63}$/. Use `llama html docs <dealId>`
+    // to list available slugs.
+    function htmlEndpoint(dealId, slug) {
+      return `/api/deals/${encodeURIComponent(dealId)}/documents/${encodeURIComponent(slug)}/html`;
+    }
+
+    // docs — list / create / archive documents on a deal.
+    //
+    // Forms:
+    //   llama html docs <dealId>                      # list
+    //   llama html docs list <dealId>                 # list (explicit)
+    //   llama html docs create <dealId> <slug> [--title "..."]
+    //   llama html docs archive <dealId> <slug>
+    if (sub === "docs") {
+      const docSub = rest[0];
+      const isExplicitSubcommand =
+        docSub === "list" ||
+        docSub === "create" ||
+        docSub === "archive";
+      if (!isExplicitSubcommand) {
+        // First positional is the dealId (the common "just list" case).
+        const dealId = rest[0];
+        if (!dealId) {
+          throw new Error(
+            "Usage: llama html docs <dealId>\n" +
+              "       llama html docs create <dealId> <slug> --title \"...\"\n" +
+              "       llama html docs archive <dealId> <slug>",
+          );
+        }
+        const data = await request(
+          "GET",
+          `/api/deals/${encodeURIComponent(dealId)}/documents`,
+        );
+        print(data);
+        return;
+      }
+      if (docSub === "list") {
+        const dealId = rest[1];
+        if (!dealId) {
+          throw new Error("Usage: llama html docs list <dealId>");
+        }
+        const data = await request(
+          "GET",
+          `/api/deals/${encodeURIComponent(dealId)}/documents`,
+        );
+        print(data);
+        return;
+      }
+      if (docSub === "create") {
+        const dealId = rest[1];
+        const slug = rest[2];
+        if (!dealId || !slug) {
+          throw new Error(
+            "Usage: llama html docs create <dealId> <slug> [--title \"...\"]",
+          );
+        }
+        const { flags } = parseFlags(rest.slice(3));
+        const title = flags.title ? String(flags.title) : slug;
+        const data = await request(
+          "POST",
+          `/api/deals/${encodeURIComponent(dealId)}/documents`,
+          { slug, title },
+        );
+        print(data);
+        return;
+      }
+      if (docSub === "archive") {
+        const dealId = rest[1];
+        const slug = rest[2];
+        if (!dealId || !slug) {
+          throw new Error("Usage: llama html docs archive <dealId> <slug>");
+        }
+        const data = await request(
+          "DELETE",
+          `/api/deals/${encodeURIComponent(dealId)}/documents/${encodeURIComponent(slug)}`,
+        );
+        print(data);
+        return;
+      }
+      throw new Error(
+        `Unknown html docs subcommand "${docSub}". Use: list / create / archive.`,
+      );
+    }
+
+    // show — fetch the current HTML. Default: print to stdout (pipeable).
+    if (sub === "show") {
+      const dealId = rest[0];
+      if (!dealId) {
+        throw new Error("Usage: llama html show <dealId> [--doc SLUG] [--out PATH] [--json]");
+      }
+      const { flags } = parseFlags(rest.slice(1));
+      const slug = typeof flags.doc === "string" && flags.doc.trim() ? flags.doc.trim() : "main";
+      const data = await request("GET", htmlEndpoint(dealId, slug));
+      if (flags.json) {
+        print(data);
+        return;
+      }
+      if (data?.empty) {
+        throw new Error(
+          `No HTML uploaded for deal ${dealId} yet. Upload via \`llama html upload\`, the web UI, or have the deal agent write it.`,
+        );
+      }
+      const html = data?.html;
+      if (typeof html !== "string") {
+        throw new Error("browse-html response missing html field.");
+      }
+      if (flags.out) {
+        const { writeFileSync } = await import("fs");
+        writeFileSync(String(flags.out), html);
+        console.error(
+          `Wrote ${html.length} bytes (v${data.version}) → ${flags.out}`,
+        );
+        return;
+      }
+      // Stdout — supports `llama html show <id> > page.html` and piping
+      // to e.g. `open -f -a Safari` for quick preview.
+      process.stdout.write(html);
+      return;
+    }
+
+    // upload — PUT a new version. Reads HTML from --file or stdin. With
+    // --assets <dir>, walks the folder, packages as a multipart bundle,
+    // and the server stores HTML + per-asset BYTEA rows atomically
+    // (deal_browse_assets table). Perfect for "Save Page As Complete"
+    // exports — the sibling `_files/` folder maps 1-to-1 to assets.
+    if (sub === "upload") {
+      const dealId = rest[0];
+      if (!dealId) {
+        throw new Error(
+          "Usage:\n" +
+            "  Update an existing artifact:\n" +
+            "    llama html upload <dealId> --doc <slug> --file PATH [--assets DIR]\n" +
+            "  Create a new artifact:\n" +
+            "    llama html upload <dealId> --new --title \"...\" --file PATH [--doc <slug>]\n" +
+            "  Stream from stdin (either form above with --stdin in place of --file PATH).\n" +
+            "\n" +
+            "Default (no --doc, no --new) targets slug 'main' but REFUSES if 'main'\n" +
+            "already has content — pass --doc main to update it explicitly, or\n" +
+            "--new --title \"...\" to add a NEW artifact alongside.",
+        );
+      }
+      const knownFlags = [
+        "doc", "slug", "new", "title",
+        "file", "stdin", "assets", "source",
+      ];
+      const { flags } = parseFlags(rest.slice(1), knownFlags);
+
+      // --slug is the natural agent guess (DB column is `document_slug`).
+      // Accept it as an alias for --doc so the failure mode that bit
+      // Gavin (silent fall-through to 'main') can't happen again.
+      if (flags.slug && !flags.doc) {
+        process.stderr.write("note: --slug accepted as alias for --doc.\n");
+        flags.doc = flags.slug;
+      } else if (flags.slug && flags.doc) {
+        process.stderr.write("note: both --doc and --slug given; --doc wins.\n");
+      }
+
+      const isNew = Boolean(flags.new);
+      const explicitDoc =
+        typeof flags.doc === "string" && flags.doc.trim()
+          ? flags.doc.trim()
+          : null;
+      const titleFlag =
+        typeof flags.title === "string" && flags.title.trim()
+          ? flags.title.trim()
+          : null;
+
+      // Pre-flight: ask the server what slugs already exist on this deal.
+      // One extra GET round-trip — cheap insurance against silent overwrite.
+      let existing = [];
+      try {
+        const docList = await request(
+          "GET",
+          `/api/deals/${encodeURIComponent(dealId)}/documents`,
+        );
+        existing = Array.isArray(docList?.documents) ? docList.documents : [];
+      } catch (err) {
+        // If the deal exists but the list endpoint somehow errors, we
+        // shouldn't block the whole upload — surface the warning and
+        // proceed in "no existing docs" mode. The server is still the
+        // ultimate gate for permission failures.
+        process.stderr.write(
+          `warning: could not pre-check existing documents (${err.message}). Continuing.\n`,
+        );
+      }
+      const findDoc = (s) =>
+        existing.find((d) => d && d.slug === s) || null;
+      const docHasHtml = (d) =>
+        Boolean(d && (d.latest_version > 0 || d.latest_updated_at));
+
+      let slug;
+      let mode; // 'created' | 'updated'
+
+      if (isNew) {
+        // Create-new branch. Caller must provide --doc OR --title (we
+        // derive the slug from the title in the latter case).
+        let candidate = explicitDoc || (titleFlag ? slugifyTitle(titleFlag) : null);
+        if (!candidate) {
+          throw new Error(
+            "--new requires --doc <slug> or --title \"...\" so the new artifact has a stable identifier.",
+          );
+        }
+        if (!isValidDocSlug(candidate)) {
+          throw new Error(
+            `slug "${candidate}" must match /^[a-z0-9][a-z0-9_-]{0,63}$/`,
+          );
+        }
+        if (findDoc(candidate)) {
+          if (explicitDoc) {
+            const existingDoc = findDoc(candidate);
+            const meta = docHasHtml(existingDoc)
+              ? ` (currently at v${existingDoc.latest_version}, last update ${existingDoc.latest_updated_at})`
+              : "";
+            throw new Error(
+              `--new --doc ${candidate} but a document with slug "${candidate}" already exists${meta}.\n` +
+                `Pick a different slug, or drop --new to UPDATE the existing one.`,
+            );
+          }
+          // Auto-resolve title collisions: foo -> foo-2 -> foo-3 -> ...
+          let suffix = 2;
+          while (findDoc(`${candidate}-${suffix}`)) suffix++;
+          const oldCandidate = candidate;
+          candidate = `${candidate}-${suffix}`;
+          process.stderr.write(
+            `note: slug "${oldCandidate}" already in use; using "${candidate}" instead.\n`,
+          );
+        }
+        slug = candidate;
+        mode = "created";
+        // Stamp the doc metadata first (title, etc.) so the UI selection
+        // page shows a nice name. PUT auto-creates the row too, but
+        // POST gives us a chance to set --title.
+        await request(
+          "POST",
+          `/api/deals/${encodeURIComponent(dealId)}/documents`,
+          { slug, title: titleFlag || slug },
+        );
+      } else if (explicitDoc) {
+        // Update an existing slug.
+        if (!isValidDocSlug(explicitDoc)) {
+          throw new Error(
+            `slug "${explicitDoc}" must match /^[a-z0-9][a-z0-9_-]{0,63}$/`,
+          );
+        }
+        const target = findDoc(explicitDoc);
+        if (!target) {
+          if (explicitDoc === "main") {
+            // 'main' is the legacy default — fine to auto-init on first
+            // upload to an empty deal.
+            slug = "main";
+            mode = "created";
+          } else {
+            const slugList = existing.length
+              ? existing.map((d) => d.slug).join(", ")
+              : "(none)";
+            throw new Error(
+              `No document with slug "${explicitDoc}" exists on this deal.\n` +
+                `To create it: add --new --title "..."\n` +
+                `Or pre-create: llama html docs create ${dealId} ${explicitDoc} --title "..."\n` +
+                `Existing slugs: ${slugList}`,
+            );
+          }
+        } else {
+          slug = explicitDoc;
+          mode = docHasHtml(target) ? "updated" : "created";
+        }
+      } else {
+        // Bare upload — no --doc, no --new. Safe-default to 'main' only
+        // if 'main' is empty / absent. Otherwise refuse, naming the
+        // existing artifact so the caller can pick an explicit intent.
+        const main = findDoc("main");
+        if (docHasHtml(main)) {
+          const versionInfo = main.latest_version
+            ? ` (v${main.latest_version}, ${main.latest_updated_at || "last update unknown"})`
+            : "";
+          const slugList = existing.length
+            ? existing.map((d) => d.slug).join(", ")
+            : "main";
+          throw new Error(
+            `Refusing to silently overwrite the existing 'main' artifact${versionInfo}.\n` +
+              `\n` +
+              `If you meant to UPDATE 'main':         --doc main\n` +
+              `If you meant to add a NEW artifact:    --new --title "<name>"\n` +
+              `\n` +
+              `Existing slugs on this deal: ${slugList}\n` +
+              `List details:                llama html docs ${dealId}`,
+          );
+        }
+        slug = "main";
+        mode = main ? "updated" : "created";
+      }
+
+      let html;
+      if (flags.file) {
+        const { readFileSync } = await import("fs");
+        html = readFileSync(String(flags.file), "utf8");
+      } else if (flags.stdin) {
+        const chunks = [];
+        for await (const chunk of process.stdin) chunks.push(chunk);
+        html = Buffer.concat(chunks).toString("utf8");
+      } else {
+        throw new Error(
+          "Pass --file <path> to upload a file, or --stdin to read from stdin.",
+        );
+      }
+      if (!html || !html.trim()) {
+        throw new Error("HTML body is empty.");
+      }
+      const source =
+        typeof flags.source === "string" && flags.source.trim()
+          ? flags.source.trim()
+          : "cli";
+
+      // No --assets → JSON path (small, faster).
+      if (!flags.assets) {
+        const data = await request("PUT", htmlEndpoint(dealId, slug), {
+          html,
+          source,
+        });
+        print({
+          ok: true,
+          mode,
+          document_slug: slug,
+          version: data?.version,
+          bytes: data?.bytes ?? Buffer.byteLength(html, "utf8"),
+          deal_uuid: dealId,
+          viewer: `${getBaseUrl()}/deals/${encodeURIComponent(dealId)}/browse/${encodeURIComponent(slug)}`,
+        });
+        return;
+      }
+
+      // --assets path → multipart bundle. Walk the asset directory,
+      // attach every file as `asset:<relativePath>`, and let the server
+      // rewrite the HTML refs to /api/deals/<id>/asset/<path>?v=N.
+      const { readFileSync, readdirSync, statSync } = await import("fs");
+      const { join, relative, sep, basename } = await import("path");
+      const assetsRoot = String(flags.assets);
+      const assetsRootStat = statSync(assetsRoot);
+      if (!assetsRootStat.isDirectory()) {
+        throw new Error(`--assets must point to a directory: ${assetsRoot}`);
+      }
+
+      // Recursively collect every file under the assets root.
+      const collected = []; // { absPath, relPath, bytes }
+      const walk = (dir) => {
+        for (const name of readdirSync(dir)) {
+          const abs = join(dir, name);
+          const st = statSync(abs);
+          if (st.isDirectory()) {
+            walk(abs);
+          } else if (st.isFile()) {
+            const rel = relative(assetsRoot, abs).split(sep).join("/");
+            collected.push({ absPath: abs, relPath: rel, bytes: st.size });
+          }
+        }
+      };
+      walk(assetsRoot);
+      if (collected.length === 0) {
+        throw new Error(`--assets directory is empty: ${assetsRoot}`);
+      }
+
+      // Some "Save Page As" exports put assets in a sibling folder named
+      // after the HTML (e.g. "Foo.html" + "Foo_files/"). When the HTML
+      // references "./Foo_files/img.png" but we walk just the inner dir,
+      // the rel paths don't match. Detect this case: if the assets root's
+      // basename is "<something>_files" or "<something> files", the HTML
+      // probably uses that prefix — prepend it to each relPath.
+      const rootName = basename(assetsRoot);
+      const looksLikeSavePageDir = /[_ ]files$/i.test(rootName);
+      const finalPaths = looksLikeSavePageDir
+        ? collected.map((c) => ({ ...c, relPath: `${rootName}/${c.relPath}` }))
+        : collected;
+
+      // Mime sniff from extension. Server defaults to
+      // application/octet-stream if blob.type is empty.
+      const mimeFor = (path) => {
+        const ext = (path.split(".").pop() || "").toLowerCase();
+        return (
+          {
+            jpg: "image/jpeg",
+            jpeg: "image/jpeg",
+            png: "image/png",
+            gif: "image/gif",
+            webp: "image/webp",
+            svg: "image/svg+xml",
+            ico: "image/x-icon",
+            avif: "image/avif",
+            css: "text/css",
+            js: "text/javascript",
+            json: "application/json",
+            woff: "font/woff",
+            woff2: "font/woff2",
+            ttf: "font/ttf",
+            otf: "font/otf",
+            mp4: "video/mp4",
+            webm: "video/webm",
+            pdf: "application/pdf",
+          }[ext] || "application/octet-stream"
+        );
+      };
+
+      const form = new FormData();
+      form.append("html", html);
+      form.append("source", source);
+      let totalBytes = 0;
+      for (const { absPath, relPath } of finalPaths) {
+        const buf = readFileSync(absPath);
+        totalBytes += buf.length;
+        // FormData wants a Blob; in Node 20+ Blob is global and accepts Buffer.
+        form.append(
+          `asset:${relPath}`,
+          new Blob([buf], { type: mimeFor(relPath) }),
+          relPath,
+        );
+      }
+
+      console.error(
+        `Uploading bundle: html ${Buffer.byteLength(html, "utf8")} bytes + ${finalPaths.length} assets (${totalBytes} bytes)`,
+      );
+
+      const headers = await getAuthHeaders();
+      const res = await fetch(`${getBaseUrl()}${htmlEndpoint(dealId, slug)}`, {
+        method: "PUT",
+        headers: { ...headers /* let fetch set the multipart boundary */ },
+        body: form,
+      });
+      const body = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        throw new Error(
+          `HTTP ${res.status}: ${body?.error || JSON.stringify(body).slice(0, 300)}`,
+        );
+      }
+      print({
+        ok: true,
+        mode,
+        document_slug: slug,
+        version: body.version,
+        asset_count: body.asset_count,
+        asset_bytes: body.asset_bytes,
+        deal_uuid: dealId,
+        viewer: `${getBaseUrl()}/deals/${encodeURIComponent(dealId)}/browse/${encodeURIComponent(slug)}`,
+      });
+      return;
+    }
+
+    // versions — list version history (newest first, includes soft-deleted).
+    if (sub === "versions") {
+      const dealId = rest[0];
+      if (!dealId) {
+        throw new Error("Usage: llama html versions <dealId> [--doc SLUG]");
+      }
+      const { flags } = parseFlags(rest.slice(1));
+      const slug =
+        typeof flags.doc === "string" && flags.doc.trim()
+          ? flags.doc.trim()
+          : "main";
+      const data = await request("GET", `${htmlEndpoint(dealId, slug)}/history`);
+      print(data);
+      return;
+    }
+
+    // restore — re-promote an old version as the new latest.
+    if (sub === "restore") {
+      const dealId = rest[0];
+      const version = Number(rest[1]);
+      if (!dealId || !Number.isFinite(version)) {
+        throw new Error(
+          "Usage: llama html restore <dealId> <version> [--doc SLUG]",
+        );
+      }
+      const { flags } = parseFlags(rest.slice(2));
+      const slug =
+        typeof flags.doc === "string" && flags.doc.trim()
+          ? flags.doc.trim()
+          : "main";
+      const data = await request(
+        "POST",
+        `${htmlEndpoint(dealId, slug)}/restore/${version}`,
+      );
+      print({
+        ok: true,
+        document_slug: slug,
+        restored_from: version,
+        new_version: data?.version,
+        deal_uuid: dealId,
+      });
+      return;
+    }
+
+    // reset — soft-delete the current HTML. /browse page reverts to empty state.
+    if (sub === "reset" || sub === "delete") {
+      const dealId = rest[0];
+      if (!dealId) {
+        throw new Error("Usage: llama html reset <dealId> [--doc SLUG]");
+      }
+      const { flags } = parseFlags(rest.slice(1));
+      const slug =
+        typeof flags.doc === "string" && flags.doc.trim()
+          ? flags.doc.trim()
+          : "main";
+      const data = await request("DELETE", htmlEndpoint(dealId, slug));
+      print({
+        ok: true,
+        document_slug: slug,
+        soft_deleted_version: data?.version ?? null,
+        deal_uuid: dealId,
+      });
+      return;
+    }
+
+    throw new Error(
+      `Unknown html subcommand "${sub || ""}". Use: docs / show / upload / versions / restore / reset.`,
+    );
+  }
+
   usage();
   process.exitCode = 1;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llamaventures/cli",
-  "version": "1.4.3",
+  "version": "1.5.0",
   "description": "CLI + MCP server for the Llama Ventures investment workbench (command.llamaventures.vc).",
   "type": "module",
   "bin": {