@llamaventures/cli 1.15.1 → 1.17.0

package/bin/llama.mjs

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 
+import { createRequire } from "module";
+import { randomUUID } from "crypto";
 import readline from "readline";
 import {
   DEFAULT_BASE_URL,
@@ -9,6 +11,7 @@ import {
   TOKEN_FILE,
   getAuthHeaders,
   getBaseUrl,
+  getLastAgentEvent,
   getToken,
   print,
   readBriefing,
@@ -33,6 +36,22 @@ import { LLAMA_CLI_CLIENT_ID, pkceLoopbackFlow, revokeToken as revokeOAuthToken
 import { deleteBundle, detectBackend, readBundle, writeBundle } from "../lib/oauth-storage.mjs";
 import { maybeNudgeUpdate, getUpdateNudge } from "../lib/version-check.mjs";
 
+const requireFromHere = createRequire(import.meta.url);
+const { version: PKG_VERSION } = requireFromHere("../package.json");
+
+function newHtmlUploadId() {
+  return `cli-${randomUUID()}`;
+}
+
+function normalizeUploadId(value) {
+  if (typeof value !== "string" || !value.trim()) return null;
+  const id = value.trim();
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(id)) {
+    throw new Error("--upload-id must be 1-128 chars: letters, numbers, dot, underscore, colon, or hyphen");
+  }
+  return id;
+}
+
 function parseFlags(args, knownFlags = null) {
   const flags = {};
   const positional = [];
@@ -71,6 +90,34 @@ function parseFlags(args, knownFlags = null) {
   return { flags, positional };
 }
 
+function agentOnboardNoAuthMessage() {
+  return `Llama Ventures team onboarding requires credentials.
+
+Team member?
+  - Run \`gcloud auth login\` with your @llamaventures.vc account, OR
+  - Mint a token at https://command.llamaventures.vc/settings/tokens
+    then \`llama token set <llc_...>\`.
+  Re-run \`llama agent-onboard\` after — the workflow contract will print.
+
+Founder or external visitor (no Llama account)?
+  Run \`llama pitch start --name "Your Name" --email "you@company.com"\`
+  to chat with our intake agent — no token required.`;
+}
+
+function agentOnboardRejectedMessage() {
+  return `Llama Ventures team onboarding requires valid credentials.
+
+Server rejected the credentials we sent. Re-mint at
+https://command.llamaventures.vc/settings/tokens, run
+\`llama token set <llc_...>\`, then re-run \`llama agent-onboard\`.`;
+}
+
+async function fetchServerAgentBriefing() {
+  const params = new URLSearchParams({ clientVersion: PKG_VERSION });
+  const result = await request("GET", `/api/agent/briefing?${params}`);
+  return result?.briefing || "";
+}
+
 function closestKnownFlag(input, candidates) {
   let best = null;
   let bestScore = Infinity;
@@ -127,6 +174,45 @@ function slugifyTitle(title) {
   return slug;
 }
 
+function parseExpectedIds(raw) {
+  const text = typeof raw === "string" ? raw : "";
+  const expected = { dealIds: [], wikiSlugs: [], raw: [] };
+  for (const item of text.split(",").map((s) => s.trim()).filter(Boolean)) {
+    const [kind, ...rest] = item.split(":");
+    const value = rest.join(":").trim();
+    if (kind === "deal" && value) expected.dealIds.push(value);
+    else if ((kind === "wiki" || kind === "slug") && value) expected.wikiSlugs.push(value);
+    else expected.raw.push(item);
+  }
+  return expected;
+}
+
+async function submitEvalFeedback(action, flags, queryText = "") {
+  const useLast = flags.last !== false;
+  const last = useLast ? getLastAgentEvent() : null;
+  const eventId =
+    flags.event && flags.event !== true
+      ? Number(flags.event)
+      : last?.lastEventId ?? null;
+  if ((action === "good" || action === "bad") && !eventId && !queryText) {
+    throw new Error(`Usage: llama eval ${action} [--last] [--reason "..."]`);
+  }
+  const body = {
+    action,
+    eventId: Number.isFinite(eventId) ? eventId : undefined,
+    query: queryText || undefined,
+    surface: flags.surface && flags.surface !== true ? String(flags.surface) : last?.lastSurface ?? undefined,
+    expected:
+      flags.expect && flags.expect !== true
+        ? parseExpectedIds(String(flags.expect))
+        : {},
+    reason: flags.reason && flags.reason !== true ? String(flags.reason) : undefined,
+    privacyLevel:
+      flags.privacy && flags.privacy !== true ? String(flags.privacy) : "internal",
+  };
+  return request("POST", "/api/agent/eval-feedback", body);
+}
+
 // 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
@@ -282,6 +368,8 @@ Agent onboarding (run once on first install):
   llama skills search "pipeline update" # discover relevant runtime skills
   llama skills show llama-pipeline      # read a skill from Command
   llama explain <url-or-object>         # explain Command URL/object status + lifecycle
+  llama eval good|bad --last            # mark the latest CLI/MCP result for eval
+  llama eval add "<query>" --expect wiki:<slug>|deal:<uuid>
 
 External pitch — talk to Llama Ventures' intake agent (no token required):
   llama pitch start --name "Jane Doe" --email "jane@acme.ai"
@@ -424,7 +512,7 @@ Mentions / Inbox:
   llama mentions unread                                # just the badge count
 
 Where does this HTML / thesis / artifact go?
-  About ONE specific deal? ........ llama html upload <dealId> --new --title "..." --file <path>
+  About ONE specific deal? ........ llama html publish <deal-id-or-name> --file <path> --title "..."
                                       (renders at /deals/<id>/browse/<slug>; see "Deal page HTML" below)
   Cross-deal / institutional? ..... llama wiki save <slug> --title "..." --file <path>.html --sources "..."
                                       (renders at /wiki/<slug>; see "Wiki" below)
@@ -442,7 +530,7 @@ Wiki:
       (.html / .htm extension auto-implies content_type=html)
       Native comments + working in-page (#) links are added automatically — just upload self-contained HTML.
   ➜ Use Wiki when the artifact is NOT tied to one specific deal — sector landscape, market map,
-    thesis, framework, methodology. For deal-specific HTML use "llama html upload <dealId>" instead.
+    thesis, framework, methodology. For deal-specific HTML use "llama html publish <deal>" instead.
   Delete / restore (soft — reversible):
     llama wiki delete <slug> [--lang en|zh]
     llama wiki restore <slug> [--lang en|zh]
@@ -461,6 +549,11 @@ Deal page HTML (hand-authored sandboxed pages on /deals/<id>/browse/<slug>):
   Each one has a stable slug. UPLOAD must declare intent — update an existing
   artifact or add a new one — to avoid silent overwrites.
 
+  Agent-safe publish path (recommended for Claude Code / Codex / Cursor):
+    llama html publish <deal-id-or-name> --file <path> [--title "..."] [--doc <slug>]
+      # Defaults to NEW doc unless --doc points at an existing slug; verifies version/bytes/sha256 after upload.
+      # Auto-detects sibling *_files asset folders unless --no-auto-assets is set.
+
   List existing artifacts:
     llama html docs <dealId>                                  # who-has-what
     llama html docs create <dealId> <slug> [--title "..."]    # pre-create a slot
@@ -489,7 +582,7 @@ Deal page HTML (hand-authored sandboxed pages on /deals/<id>/browse/<slug>):
   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.
+  update_deal_browse_html tool and the MCP html_upload_file 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]
@@ -525,6 +618,7 @@ Common:
   llama agent bootstrap             live Llama OS skill manifest from Command
   llama skills search "<query>"     discover which skill to read
   llama explain <url-or-object>     explain Command URLs, 404s, deleted objects
+  llama eval bad --last              mark latest CLI/MCP result as an eval candidate
 
 Command groups — run \`llama help <group>\` for that group's commands:
   deal        create · show · feed · update · enrich · search · collaborators · links · delete
@@ -532,6 +626,7 @@ Command groups — run \`llama help <group>\` for that group's commands:
   facts       deal facts + skill corrections (the sourced, trust-rated layer)
   timeline    timeline · posts · mentions
   wiki        cross-deal knowledge entries (markdown or HTML)
+  eval        mark real CLI/MCP searches good/bad or add a golden-query candidate
   memo        long-form HTML investment memo
   html        deal-specific HTML artifacts (/deals/<id>/browse/<slug>)
   pitch       external founder intake (no token needed)
@@ -865,18 +960,15 @@ async function runPitchRepl() {
 async function main() {
   const [area, action, ...rest] = process.argv.slice(2);
   if (area === "--version" || area === "-v" || area === "version") {
-    const { createRequire } = await import("module");
-    const requireFromHere = createRequire(import.meta.url);
-    const { version } = requireFromHere("../package.json");
     // `llama version --check` — explicitly check npm for a newer release and
     // print the upgrade line (or "up to date"). Lets an agent surface the
     // nudge on demand, separate from the throttled, TTY-gated auto-nudge.
     if (action === "--check" || action === "check") {
       const nudge = await getUpdateNudge();
-      console.log(nudge || `llama CLI ${version} — up to date`);
+      console.log(nudge || `llama CLI ${PKG_VERSION} — up to date`);
       return;
     }
-    console.log(version);
+    console.log(PKG_VERSION);
     return;
   }
   if (!area || area === "help" || area === "--help" || area === "-h") {
@@ -897,12 +989,13 @@ async function main() {
     return;
   }
 
-  // `llama agent-onboard` — print the bundled AGENT_BRIEFING.md so an AI
-  // agent reads it once and internalises the Llama Ventures workflow
-  // contract. Same content the `agent_briefing` MCP prompt returns.
+  // `llama agent-onboard` — fetch the server-owned Agent Runtime Contract
+  // so an AI agent reads the current Llama Ventures workflow contract. The
+  // bundled AGENT_BRIEFING.md is now only a fallback when the server route
+  // is unavailable during rollout.
   // Also: `llama agent onboard` (two-word form) for symmetry.
   //
-  // Gated behind /api/me — without valid credentials we print a short
+  // Gated behind Command auth — without valid credentials we print a short
   // bootstrap stub instead. Stops unauthenticated callers from harvesting
   // internal command surface / workflow conventions just by running the
   // public CLI.
@@ -912,39 +1005,24 @@ async function main() {
   ) {
     const headers = await getAuthHeaders();
     if (Object.keys(headers).length === 0) {
-      console.log(
-`Llama Ventures team onboarding requires credentials.
-
-Team member?
-  - Run \`gcloud auth login\` with your @llamaventures.vc account, OR
-  - Mint a token at https://command.llamaventures.vc/settings/tokens
-    then \`llama token set <llc_...>\`.
-  Re-run \`llama agent-onboard\` after — the workflow contract will print.
-
-Founder or external visitor (no Llama account)?
-  Run \`llama pitch start --name "Your Name" --email "you@company.com"\`
-  to chat with our intake agent — no token required.`
-      );
+      console.log(agentOnboardNoAuthMessage());
       return;
     }
     try {
-      await request("GET", "/api/me");
+      const briefing = await fetchServerAgentBriefing();
+      process.stdout.write(briefing || readBriefing());
     } catch (e) {
       const msg = e?.message || "";
       if (msg.includes("Error[UNAUTHORIZED]") || msg.includes("Error[NO_AUTH]")) {
-        console.log(
-`Llama Ventures team onboarding requires valid credentials.
-
-Server rejected the credentials we sent. Re-mint at
-https://command.llamaventures.vc/settings/tokens, run
-\`llama token set <llc_...>\`, then re-run \`llama agent-onboard\`.`
-        );
+        console.log(agentOnboardRejectedMessage());
         process.exitCode = 1;
         return;
       }
-      throw e;
+      process.stderr.write(
+        `warning: server agent briefing unavailable (${msg}); using bundled fallback.\n`,
+      );
+      process.stdout.write(readBriefing());
     }
-    process.stdout.write(readBriefing());
     return;
   }
 
@@ -954,6 +1032,7 @@ https://command.llamaventures.vc/settings/tokens, run
   if (area === "agent" && action === "bootstrap") {
     const { flags } = parseFlags(rest, ["json", "limit"]);
     const params = new URLSearchParams();
+    params.set("clientVersion", PKG_VERSION);
     if (flags.limit && flags.limit !== true) params.set("limit", String(flags.limit));
     const manifest = await request("GET", `/api/agent/manifest${params.toString() ? `?${params}` : ""}`);
     if (flags.json) {
@@ -1037,6 +1116,43 @@ https://command.llamaventures.vc/settings/tokens, run
     return;
   }
 
+  if (area === "eval") {
+    const sub = action;
+    if (sub === "good" || sub === "bad") {
+      const { flags, positional } = parseFlags(rest, [
+        "last",
+        "event",
+        "reason",
+        "expect",
+        "surface",
+        "privacy",
+      ]);
+      const q = positional.join(" ").trim();
+      print(await submitEvalFeedback(sub, flags, q));
+      return;
+    }
+    if (sub === "add") {
+      const { flags, positional } = parseFlags(rest, [
+        "event",
+        "expect",
+        "reason",
+        "surface",
+        "privacy",
+      ]);
+      const q = positional.join(" ").trim();
+      if (!q && !flags.event) {
+        throw new Error(
+          `Usage: llama eval add "<query>" --surface deal|wiki --expect wiki:<slug>|deal:<uuid>`,
+        );
+      }
+      print(await submitEvalFeedback("add", flags, q));
+      return;
+    }
+    throw new Error(
+      "Usage: llama eval good|bad [--last] [--reason ...] OR llama eval add \"<query>\" --expect wiki:<slug>|deal:<uuid>",
+    );
+  }
+
   // `llama pitch ...` — external founder-pitch family. No Llama token
   // required; bootstraps a session against /api/external/* via PoW + cookie.
   // See lib/external.mjs and AGENT_BRIEFING.md for the full surface.
@@ -2427,10 +2543,268 @@ Routing — is this the right command?
     // --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.
+    const MAX_HTML_BYTES = 5 * 1024 * 1024;
+    const MAX_ASSET_BYTES = 50 * 1024 * 1024;
+    const MAX_BUNDLE_BYTES = 100 * 1024 * 1024;
+
     function htmlEndpoint(dealId, slug) {
       return `/api/deals/${encodeURIComponent(dealId)}/documents/${encodeURIComponent(slug)}/html`;
     }
 
+    function looksLikeHtml(html) {
+      const head = String(html || "").trim().slice(0, 256).toLowerCase();
+      return head.startsWith("<!doctype html") || head.startsWith("<html");
+    }
+
+    function extractHtmlTitle(html) {
+      const title = String(html || "").match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1];
+      if (!title) return null;
+      const clean = title.replace(/\s+/g, " ").trim();
+      return clean ? clean.slice(0, 200) : null;
+    }
+
+    function docHasHtml(d) {
+      return Boolean(d && (d.latest_version > 0 || d.latest_updated_at));
+    }
+
+    function findDocBySlug(docs, slug) {
+      return docs.find((d) => d && d.slug === slug) || null;
+    }
+
+    function nextAvailableSlug(base, docs) {
+      let candidate = base;
+      let suffix = 2;
+      while (findDocBySlug(docs, candidate)) {
+        candidate = `${base.slice(0, Math.max(1, 64 - String(suffix).length - 1))}-${suffix}`;
+        suffix += 1;
+      }
+      return candidate;
+    }
+
+    function mimeForAsset(path) {
+      const ext = (String(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"
+      );
+    }
+
+    async function listHtmlDocs(dealId) {
+      const docList = await request(
+        "GET",
+        `/api/deals/${encodeURIComponent(dealId)}/documents`,
+      );
+      return Array.isArray(docList?.documents) ? docList.documents : [];
+    }
+
+    async function resolveDealForHtmlPublish(dealRef) {
+      const ref = String(dealRef || "").trim();
+      if (!ref) throw new Error("deal id or name is required");
+      try {
+        await listHtmlDocs(ref);
+        return { dealId: ref, resolvedFrom: "id" };
+      } catch {
+        // Not a readable deal id; fall through to pipeline search.
+      }
+
+      const result = await searchDeals(ref, { limit: 10 });
+      const deals = Array.isArray(result?.deals) ? result.deals : [];
+      if (deals.length === 0) {
+        throw new Error(
+          `No deal matched "${ref}". Run \`llama deal search "${ref}"\` first and pass the exact deal id.`,
+        );
+      }
+      const exact = deals.filter(
+        (d) => String(d.companyName || "").toLowerCase() === ref.toLowerCase(),
+      );
+      const candidates = exact.length > 0 ? exact : deals;
+      if (candidates.length !== 1) {
+        const lines = candidates
+          .slice(0, 8)
+          .map((d) => `- ${d.companyName || "(unnamed)"} — ${d.uuid || d.id}`)
+          .join("\n");
+        throw new Error(
+          `Deal name "${ref}" matched multiple records. Re-run with the exact deal id:\n${lines}`,
+        );
+      }
+      const dealId = candidates[0]?.uuid || candidates[0]?.id;
+      if (!dealId) {
+        throw new Error(`Deal search matched "${ref}" but did not return a deal id.`);
+      }
+      return {
+        dealId,
+        dealName: candidates[0]?.companyName || ref,
+        resolvedFrom: "search",
+      };
+    }
+
+    async function detectSiblingAssetsDir(filePath) {
+      const { existsSync, statSync } = await import("fs");
+      const { dirname, basename, extname, join } = await import("path");
+      const dir = dirname(filePath);
+      const ext = extname(filePath);
+      const stem = basename(filePath, ext);
+      const candidates = [
+        `${stem}_files`,
+        `${stem} files`,
+        `${basename(filePath)}_files`,
+      ];
+      for (const name of candidates) {
+        const p = join(dir, name);
+        if (existsSync(p) && statSync(p).isDirectory()) return p;
+      }
+      return null;
+    }
+
+    async function collectAssets(assetsRoot) {
+      const { readFileSync, readdirSync, statSync } = await import("fs");
+      const { join, relative, sep, basename } = await import("path");
+      const rootStat = statSync(assetsRoot);
+      if (!rootStat.isDirectory()) {
+        throw new Error(`assets path must be a directory: ${assetsRoot}`);
+      }
+      const collected = [];
+      const walk = (dir) => {
+        for (const name of readdirSync(dir)) {
+          const absPath = join(dir, name);
+          const st = statSync(absPath);
+          if (st.isDirectory()) {
+            walk(absPath);
+          } else if (st.isFile()) {
+            const relPath = relative(assetsRoot, absPath).split(sep).join("/");
+            collected.push({ absPath, relPath, bytes: st.size });
+          }
+        }
+      };
+      walk(assetsRoot);
+      if (collected.length === 0) {
+        throw new Error(`assets directory is empty: ${assetsRoot}`);
+      }
+      const rootName = basename(assetsRoot);
+      const looksLikeSavePageDir = /[_ ]files$/i.test(rootName);
+      const finalPaths = looksLikeSavePageDir
+        ? collected.map((c) => ({ ...c, relPath: `${rootName}/${c.relPath}` }))
+        : collected;
+      let totalBytes = 0;
+      for (const item of finalPaths) {
+        if (item.relPath.split("/").some((seg) => seg === "..")) {
+          throw new Error(`asset path "${item.relPath}" contains "..", refused`);
+        }
+        if (item.bytes > MAX_ASSET_BYTES) {
+          throw new Error(
+            `asset "${item.relPath}" is ${item.bytes} bytes; cap is ${MAX_ASSET_BYTES}`,
+          );
+        }
+        totalBytes += item.bytes;
+        if (totalBytes > MAX_BUNDLE_BYTES) {
+          throw new Error(`total asset bytes exceeds ${MAX_BUNDLE_BYTES}`);
+        }
+      }
+      return {
+        assets: finalPaths.map((item) => ({
+          ...item,
+          data: readFileSync(item.absPath),
+          contentType: mimeForAsset(item.relPath),
+        })),
+        totalBytes,
+      };
+    }
+
+    async function uploadHtmlPayload({ dealId, slug, html, source, assetsDir, uploadId }) {
+      if (!assetsDir) {
+        return request("PUT", htmlEndpoint(dealId, slug), {
+          html,
+          source,
+          client_upload_id: uploadId,
+        }, {
+          headers: { "X-Llama-Upload-Id": uploadId },
+        });
+      }
+      const { assets, totalBytes } = await collectAssets(assetsDir);
+      const form = new FormData();
+      form.append("html", html);
+      form.append("source", source);
+      form.append("client_upload_id", uploadId);
+      for (const asset of assets) {
+        form.append(
+          `asset:${asset.relPath}`,
+          new Blob([asset.data], { type: asset.contentType }),
+          asset.relPath,
+        );
+      }
+      console.error(
+        `Uploading bundle: html ${Buffer.byteLength(html, "utf8")} bytes + ${assets.length} assets (${totalBytes} bytes)`,
+      );
+      const headers = await getAuthHeaders();
+      const res = await fetch(`${getBaseUrl()}${htmlEndpoint(dealId, slug)}`, {
+        method: "PUT",
+        headers: { ...headers, "X-Llama-Upload-Id": uploadId },
+        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;
+    }
+
+    async function verifyHtmlUpload({ dealId, slug, expectedVersion, expectedBytes, expectedSha256 }) {
+      const latest = await request("GET", htmlEndpoint(dealId, slug));
+      if (latest?.empty) {
+        throw new Error(`verification failed: ${slug} came back empty after upload`);
+      }
+      if (expectedVersion != null && Number(latest.version) !== Number(expectedVersion)) {
+        throw new Error(
+          `verification failed: expected version ${expectedVersion}, got ${latest.version}`,
+        );
+      }
+      if (
+        expectedBytes != null &&
+        latest.bytes != null &&
+        Number(latest.bytes) !== Number(expectedBytes)
+      ) {
+        throw new Error(
+          `verification failed: expected ${expectedBytes} bytes, got ${latest.bytes}`,
+        );
+      }
+      if (
+        expectedSha256 &&
+        latest.sha256 &&
+        String(latest.sha256) !== String(expectedSha256)
+      ) {
+        throw new Error(
+          `verification failed: expected sha256 ${expectedSha256}, got ${latest.sha256}`,
+        );
+      }
+      return {
+        ok: true,
+        version: latest.version,
+        bytes: latest.bytes,
+        sha256: latest.sha256,
+        created_at: latest.created_at,
+      };
+    }
+
     // Surface a clean `linked_wiki` field on linked docs so the listing
     // reads as "this card points at wiki/<slug>" rather than exposing the
     // raw source_wiki_* columns. Non-linked docs are returned unchanged.
@@ -2642,6 +3016,174 @@ Routing — is this the right command?
       return;
     }
 
+    // publish — agent-safe high-level upload path. The agent gives us a file
+    // path + a deal id/name; the CLI handles search, slug decisions, asset
+    // discovery, upload, and read-after-write verification.
+    if (sub === "publish") {
+      const dealRef = rest[0];
+      const knownFlags = [
+        "file", "title", "doc", "slug", "new", "update",
+        "assets", "no-auto-assets", "source", "no-verify", "upload-id",
+      ];
+      const { flags } = parseFlags(rest.slice(1), knownFlags);
+      if (!dealRef || !flags.file || flags.file === true) {
+        throw new Error(
+          "Usage: llama html publish <deal-id-or-name> --file PATH [--title \"...\"] [--doc <slug>] [--update|--new] [--assets DIR]",
+        );
+      }
+      if (flags.slug && !flags.doc) {
+        process.stderr.write("note: --slug accepted as alias for --doc.\n");
+        flags.doc = flags.slug;
+      }
+      const wantsNew = boolFlag(flags, "new");
+      const wantsUpdate = boolFlag(flags, "update");
+      if (wantsNew && wantsUpdate) {
+        throw new Error("Choose only one of --new or --update.");
+      }
+
+      const filePath = String(flags.file);
+      const { readFileSync, statSync } = await import("fs");
+      const { basename, extname } = await import("path");
+      const fileStat = statSync(filePath);
+      if (!fileStat.isFile()) {
+        throw new Error(`--file must point to a readable HTML file: ${filePath}`);
+      }
+      const html = readFileSync(filePath, "utf8");
+      if (!html.trim()) throw new Error("HTML body is empty.");
+      const htmlBytes = Buffer.byteLength(html, "utf8");
+      if (htmlBytes > MAX_HTML_BYTES) {
+        throw new Error(
+          `HTML body is ${(htmlBytes / 1024 / 1024).toFixed(2)} MB; cap is 5 MB. Put large media in an asset folder or Drive, not inline HTML.`,
+        );
+      }
+      if (!looksLikeHtml(html)) {
+        throw new Error("HTML must start with <!doctype html> or <html.");
+      }
+
+      const resolved = await resolveDealForHtmlPublish(dealRef);
+      const docs = await listHtmlDocs(resolved.dealId);
+      const explicitDoc =
+        typeof flags.doc === "string" && flags.doc.trim()
+          ? flags.doc.trim()
+          : null;
+      const title =
+        typeof flags.title === "string" && flags.title.trim()
+          ? flags.title.trim()
+          : extractHtmlTitle(html) || basename(filePath, extname(filePath));
+      let slug;
+      let mode;
+      let createdMetadata = false;
+
+      if (explicitDoc) {
+        if (!isValidDocSlug(explicitDoc)) {
+          throw new Error(
+            `slug "${explicitDoc}" must match /^[a-z0-9][a-z0-9_-]{0,63}$/`,
+          );
+        }
+        const existingDoc = findDocBySlug(docs, explicitDoc);
+        if (wantsNew && existingDoc) {
+          throw new Error(
+            `--new requested, but document "${explicitDoc}" already exists on this deal.`,
+          );
+        }
+        if (wantsUpdate && !existingDoc) {
+          throw new Error(
+            `--update requested, but document "${explicitDoc}" does not exist on this deal.`,
+          );
+        }
+        slug = explicitDoc;
+        mode = existingDoc && docHasHtml(existingDoc) ? "updated" : "created";
+        if (!existingDoc) createdMetadata = true;
+      } else {
+        const baseSlug = slugifyTitle(title) || slugifyTitle(basename(filePath, extname(filePath)));
+        if (!baseSlug) {
+          throw new Error(
+            "Could not derive a valid slug from the title or filename. Pass --doc <slug>.",
+          );
+        }
+        const existingDoc = findDocBySlug(docs, baseSlug);
+        if (wantsUpdate) {
+          if (!existingDoc) {
+            throw new Error(
+              `--update requested, but derived document "${baseSlug}" does not exist. Pass --doc <existing-slug> or drop --update to create a new doc.`,
+            );
+          }
+          slug = baseSlug;
+          mode = docHasHtml(existingDoc) ? "updated" : "created";
+        } else {
+          slug = existingDoc ? nextAvailableSlug(baseSlug, docs) : baseSlug;
+          mode = "created";
+          createdMetadata = true;
+          if (existingDoc) {
+            process.stderr.write(
+              `note: "${baseSlug}" already exists; publishing as new document "${slug}". Use --update or --doc ${baseSlug} to replace it.\n`,
+            );
+          }
+        }
+      }
+
+      if (createdMetadata) {
+        await request(
+          "POST",
+          `/api/deals/${encodeURIComponent(resolved.dealId)}/documents`,
+          { slug, title },
+        );
+      }
+
+      let assetsDir =
+        typeof flags.assets === "string" && flags.assets.trim()
+          ? flags.assets.trim()
+          : null;
+      if (!assetsDir && !boolFlag(flags, "no-auto-assets")) {
+        assetsDir = await detectSiblingAssetsDir(filePath);
+        if (assetsDir) {
+          process.stderr.write(`note: auto-detected asset folder ${assetsDir}\n`);
+        }
+      }
+      const source =
+        typeof flags.source === "string" && flags.source.trim()
+          ? flags.source.trim()
+          : "cli";
+      const uploadId = normalizeUploadId(flags["upload-id"]) || newHtmlUploadId();
+      const uploaded = await uploadHtmlPayload({
+        dealId: resolved.dealId,
+        slug,
+        html,
+        source,
+        assetsDir,
+        uploadId,
+      });
+      const verification = boolFlag(flags, "no-verify")
+        ? { ok: false, skipped: true }
+        : await verifyHtmlUpload({
+            dealId: resolved.dealId,
+            slug,
+            expectedVersion: uploaded?.version,
+            expectedBytes: uploaded?.bytes,
+            expectedSha256: uploaded?.sha256,
+          });
+
+      print({
+        ok: true,
+        mode,
+        deal_uuid: resolved.dealId,
+        resolved_from: resolved.resolvedFrom,
+        deal_name: resolved.dealName,
+        document_slug: slug,
+        title,
+        version: uploaded?.version,
+        bytes: uploaded?.bytes ?? verification.bytes ?? htmlBytes,
+        sha256: uploaded?.sha256 ?? verification.sha256,
+        client_upload_id: uploaded?.client_upload_id ?? uploadId,
+        idempotent_replay: uploaded?.idempotent_replay,
+        asset_count: uploaded?.asset_count,
+        asset_bytes: uploaded?.asset_bytes,
+        verified: verification,
+        viewer: `${getBaseUrl()}/deals/${encodeURIComponent(resolved.dealId)}/browse/${encodeURIComponent(slug)}`,
+      });
+      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
@@ -2676,7 +3218,7 @@ Routing — is this the right command?
       }
       const knownFlags = [
         "doc", "slug", "new", "title",
-        "file", "stdin", "assets", "source",
+        "file", "stdin", "assets", "source", "upload-id",
       ];
       const { flags } = parseFlags(rest.slice(1), knownFlags);
 
@@ -2845,12 +3387,16 @@ Routing — is this the right command?
         typeof flags.source === "string" && flags.source.trim()
           ? flags.source.trim()
           : "cli";
+      const uploadId = normalizeUploadId(flags["upload-id"]) || newHtmlUploadId();
 
       // No --assets → JSON path (small, faster).
       if (!flags.assets) {
         const data = await request("PUT", htmlEndpoint(dealId, slug), {
           html,
           source,
+          client_upload_id: uploadId,
+        }, {
+          headers: { "X-Llama-Upload-Id": uploadId },
         });
         print({
           ok: true,
@@ -2858,6 +3404,9 @@ Routing — is this the right command?
           document_slug: slug,
           version: data?.version,
           bytes: data?.bytes ?? Buffer.byteLength(html, "utf8"),
+          sha256: data?.sha256,
+          client_upload_id: data?.client_upload_id ?? uploadId,
+          idempotent_replay: data?.idempotent_replay,
           deal_uuid: dealId,
           viewer: `${getBaseUrl()}/deals/${encodeURIComponent(dealId)}/browse/${encodeURIComponent(slug)}`,
         });
@@ -2937,6 +3486,7 @@ Routing — is this the right command?
       const form = new FormData();
       form.append("html", html);
       form.append("source", source);
+      form.append("client_upload_id", uploadId);
       let totalBytes = 0;
       for (const { absPath, relPath } of finalPaths) {
         const buf = readFileSync(absPath);
@@ -2956,7 +3506,11 @@ Routing — is this the right command?
       const headers = await getAuthHeaders();
       const res = await fetch(`${getBaseUrl()}${htmlEndpoint(dealId, slug)}`, {
         method: "PUT",
-        headers: { ...headers /* let fetch set the multipart boundary */ },
+        headers: {
+          ...headers,
+          "X-Llama-Upload-Id": uploadId,
+          /* let fetch set the multipart boundary */
+        },
         body: form,
       });
       const body = await res.json().catch(() => ({}));
@@ -2970,6 +3524,10 @@ Routing — is this the right command?
         mode,
         document_slug: slug,
         version: body.version,
+        bytes: body.bytes,
+        sha256: body.sha256,
+        client_upload_id: body.client_upload_id ?? uploadId,
+        idempotent_replay: body.idempotent_replay,
         asset_count: body.asset_count,
         asset_bytes: body.asset_bytes,
         deal_uuid: dealId,
@@ -3044,7 +3602,7 @@ Routing — is this the right command?
     }
 
     throw new Error(
-      `Unknown html subcommand "${sub || ""}". Use: docs / link / unlink / show / upload / versions / restore / reset.`,
+      `Unknown html subcommand "${sub || ""}". Use: docs / link / unlink / show / publish / upload / versions / restore / reset.`,
     );
   }