@llamaventures/cli 1.4.4 → 1.6.0

package/AGENT_BRIEFING.md

@@ -29,13 +29,69 @@ Don't:
 
 Conversation produces value → that value flows somewhere. This is not optional.
 
+### Where does this HTML / thesis / artifact go? (decision tree)
+
+When the user hands you an HTML page, thesis write-up, market map, dashboard, IC memo, sector landscape — anything that isn't a one-off note — pick the destination in this order. **Llama Command native (the workbench) outranks Netlify for everything internal.** Only escape to Netlify when the page is truly going to a public / founder-facing URL.
+
+```
+HTML / thesis / artifact in hand
+        │
+        ▼
+  ┌─────────────────────────────────────────────────┐
+  │ Is it about ONE specific company or deal?       │
+  │  (deal IC memo · dashboard for X · X 的 thesis  │
+  │   · founder briefing for X · X 的 2×2 …)        │
+  └──────────────┬──────────────────────────────────┘
+                 │
+        yes ────►│  → Llama Command DEAL page
+                 │    `llama html upload <dealId> --new --title "..." --file <path>`
+                 │    Renders at /deals/<id>/browse/<slug>.
+                 │    Use --doc <slug> + --file to update an existing one.
+                 │
+        no  ────►│  Is it cross-deal / institutional knowledge?
+                 │   (sector landscape · market map · framework · firm-level
+                 │    thesis · methodology · "AI infra in 2026" …)
+                 │
+                 │       yes ──►  → Llama Command WIKI entry
+                 │                  Markdown body:
+                 │                    `llama wiki save <slug> --title "..." \`
+                 │                    `  --content "..." --sources "..."`
+                 │                  Standalone HTML page (full-viewport iframe):
+                 │                    `llama wiki save <slug> --title "..." \`
+                 │                    `  --file <path>.html --sources "..."`
+                 │                  Renders at /wiki/<slug>. Sources mandatory.
+                 │
+                 │       no  ──►  Likely doesn't need to live anywhere
+                 │                durable — confirm with the user before
+                 │                inventing a destination.
+                 ▼
+  ┌─────────────────────────────────────────────────┐
+  │ Does the user EXPLICITLY say "share with        │
+  │ founder" / "public share link" / "give it to    │
+  │ <external person>" / "publish publicly"?        │
+  └──────────────┬──────────────────────────────────┘
+                 │
+        no  ────►│  → STAY on Llama Command. Don't reach for Netlify.
+                 │
+        yes ────►│  → Netlify (only this case).
+                 │    Use the `netlify-access-guard` workflow:
+                 │    server-side password + edge 401 verification.
+                 │    Verify enforcement is at the Netlify edge, not a
+                 │    browser-side JS fake.
+```
+
+**Default bias:** when in doubt, route to Llama Command. It has auth, audit, search, backlinks, and lives next to the rest of the team's context. Netlify is the escape hatch for genuinely-external surfaces — not "where pretty HTML goes."
+
+The table below details the exact CLI for each destination.
+
 | Type | Destination | How |
 |---|---|---|
 | 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>`) | **`llama html upload <dealId> --file <path> [--assets <dir>]`** — this is the **default** path when the user says "deploy to llama", "deploy to llama command", "部署到 llama command", "put this HTML on the deal page", "在 deal 里看这个". Do NOT default to Netlify for internal pages. |
+| **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) |
+| Insights, decisions, framework improvements | Wiki (markdown) | `llama wiki save <slug> --content "..."` (with attribution — see below) |
+| **HTML wiki entry — standalone HTML page hosted at `/wiki/<slug>`** (sector landscape, market map, dashboard, hand-styled thesis page) | **Wiki (HTML)** | `llama wiki save <slug> --title "..." --file <path.html> --sources "..."`. Auto-detects content_type=html from extension. Public page is full-viewport sandboxed iframe takeover (no wiki chrome). Sources/status/title still required; appears in `wiki search` + backlinks. Use when the user says "deploy this HTML to wiki", "wiki 词条", "make this page a wiki entry". HTML must be self-contained (inline CSS/JS, image data URIs or external URLs) — asset bundles aren't supported on wiki yet. |
 | 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 |
 
@@ -108,17 +164,47 @@ 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> (PR #81)
+# 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".
-llama html upload <dealId> --file ./report.html [--assets ./assets]   # PUT new version (auto-increments)
-llama html show <dealId> [--out path] [--json]                         # current HTML → stdout
-llama html versions <dealId>                                           # version history (incl. soft-deleted)
-llama html restore <dealId> <version>                                  # promote old version to latest
-llama html reset <dealId>                                              # soft-delete latest (browse reverts to empty)
+# 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 "..."
+llama wiki read <slug> [--lang en|zh]
+
+# Markdown entry (default):
+llama wiki save <slug> --title "..." --content "..." --sources "url1;url2"
+
+# HTML entry — standalone page at /wiki/<slug>, full-viewport sandboxed iframe:
+llama wiki save <slug> --title "..." --file path.html --sources "..." [--content-type html]
+#   .html / .htm extension auto-implies content_type=html.
+#   --content-type html (or markdown) overrides the inference.
+#   Refuses to switch content_type on an existing slug; delete + re-create
+#   if you really mean to change format.
 
 # Timeline + posts
 llama timeline <dealId>
@@ -145,7 +231,7 @@ Tools available:
 - `auth_status` — verify creds + identity (call first if anything 401s)
 - `deal_search` / `deal_show` / `deal_create` / `deal_update`
 - `brief_blocks` / `brief_add_text` / `brief_add_link` / `brief_add_callout`
-- `wiki_search` / `wiki_save`
+- `wiki_search` / `wiki_save` (accepts `content_type: 'markdown' | 'html'` — HTML entries render as full-viewport sandboxed iframe at `/wiki/<slug>`)
 - `timeline` / `post`
 - `mentions_list`
 - `pitch_start` / `pitch_send_message` / `pitch_upload_file` / `pitch_status` / `pitch_finalize` — public intake (no Llama token needed; for founders / EAs / external agents)

package/bin/llama-mcp.mjs

@@ -328,24 +328,56 @@ server.registerTool(
   "wiki_save",
   {
     description:
-      "Create or update a wiki page. Content should be markdown with attribution " +
-      "blocks (**[Name · YYYY-MM-DD · source · fact|opinion]**) for traceability. " +
-      "`sources` is a separate citation list (URLs, doc names, or meeting references) " +
-      "— at least one is required; URLs embedded inside `content` do not count.",
+      "Create or update a wiki page — Llama's CROSS-DEAL / institutional " +
+      "knowledge surface (sector landscape · market map · thesis · framework · " +
+      "methodology · anything not tied to ONE specific deal). Renders at " +
+      "/wiki/<slug>. " +
+      "**Routing — decide BEFORE calling:** " +
+      "(a) Deal-specific HTML (IC memo for X, dashboard for X) → use " +
+      "`html_upload` instead, NOT this. " +
+      "(b) Cross-deal / institutional (this tool) → /wiki/<slug>. " +
+      "(c) Founder-facing public share → Netlify only when user explicitly " +
+      "says so; Llama Command outranks Netlify for everything internal. " +
+      "By default `content` is markdown with attribution blocks " +
+      "(**[Name · YYYY-MM-DD · source · fact|opinion]**) for traceability. " +
+      "Set `content_type: 'html'` to deploy a standalone HTML page as the " +
+      "wiki entry (full-viewport sandboxed iframe takeover on /wiki/<slug>; " +
+      "the HTML itself is the page — no wiki chrome). `sources` is a " +
+      "separate citation list (URLs, doc names, or meeting references) — " +
+      "at least one required; URLs inside `content` do not count. For HTML " +
+      "asset bundles use the `llama wiki save --file ... --assets ...` CLI " +
+      "path; MCP only supports single-file HTML.",
     inputSchema: {
       slug: z.string().describe("kebab-case slug"),
       title: z.string(),
-      content: z.string().describe("markdown content"),
+      content: z
+        .string()
+        .describe(
+          "body — markdown source by default, or raw HTML when content_type='html'"
+        ),
       sources: z
         .array(z.string())
         .min(1)
         .describe(
           "citation list — URLs, doc names, or meeting references. At least one required."
         ),
+      content_type: z
+        .enum(["markdown", "html"])
+        .optional()
+        .describe(
+          "'markdown' (default) renders via the wiki markdown pipeline. " +
+            "'html' stores the body as a standalone HTML page (sandboxed iframe)."
+        ),
     },
   },
-  async ({ slug, title, content, sources }) =>
-    callApi("POST", "/api/wiki/save", { slug, title, content, sources })
+  async ({ slug, title, content, sources, content_type }) =>
+    callApi("POST", "/api/wiki/save", {
+      slug,
+      title,
+      content,
+      sources,
+      ...(content_type ? { content_type } : {}),
+    })
 );
 
 // ============================================================
@@ -707,7 +739,16 @@ server.registerTool(
   "html_upload",
   {
     description:
-      "Upload (PUT) a new HTML version for a deal's /browse page. " +
+      "Upload (PUT) a new HTML version for a SPECIFIC DEAL's /browse page " +
+      "(deal-scoped artifact: IC memo for X · dashboard for X · 2×2 for X). " +
+      "Renders at /deals/<id>/browse/<slug>. " +
+      "**Routing — pick the right destination BEFORE calling this:** " +
+      "(a) Deal-specific HTML (this tool) → /deals/<id>/browse/<slug>. " +
+      "(b) Cross-deal / institutional / thesis / sector landscape → use " +
+      "`wiki_save` with content_type='html' instead (/wiki/<slug>). " +
+      "(c) Founder-facing public share link → escape to Netlify only when " +
+      "the user explicitly says 'share with founder' / 'publish publicly'; " +
+      "Llama Command outranks Netlify for everything internal. " +
       "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 " +

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
@@ -251,10 +324,25 @@ Mentions / Inbox:
   llama mentions resolve <mentionId>                   # mark thread resolved (idempotent)
   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>
+                                      (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)
+  Founder-facing public share? .... Netlify (with netlify-access-guard skill), only when user explicitly
+                                      says "share publicly". Llama Command outranks Netlify for everything
+                                      internal — don't reach for Netlify by default.
+
 Wiki:
   llama wiki search <query>
   llama wiki read <slug>
-  llama wiki save <slug> --title "..." --content "..." --sources "url1;url2" [--type company] [--related "A;B"]
+  Markdown entry (default):
+    llama wiki save <slug> --title "..." --content "..." --sources "url1;url2" [--type company] [--related "A;B"]
+  HTML entry — standalone HTML page at /wiki/<slug> (full-viewport sandboxed iframe):
+    llama wiki save <slug> --title "..." --file path.html --sources "..." [--content-type html]
+      (.html / .htm extension auto-implies content_type=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.
 
 Memo (long-form HTML investment memo — Memo tab in the UI):
   llama memo show <dealId> [--out <path>] [--json]          # default: html → stdout (pipeable to file / browser)
@@ -262,14 +350,33 @@ 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 page on /deals/<id>/browse):
-  llama html show <dealId> [--out <path>] [--json]           # default: current html → stdout (pipeable)
-  llama html upload <dealId> --file <path> [--assets DIR]    # PUT a new version (auto increments).
-                                                             # --assets bundles a sibling folder of images / fonts / css
-                                                             # (e.g. "Save Page As Complete" exports — the _files/ dir)
-  llama html versions <dealId>                               # list version history (incl. soft-deleted)
-  llama html restore <dealId> <version>                      # promote an old version to new latest
-  llama html reset <dealId>                                  # soft-delete latest; /browse reverts to empty state
+Deal page HTML (hand-authored sandboxed pages on /deals/<id>/browse/<slug>):
+  ➜ Use this for DEAL-SPECIFIC artifacts: IC memo for X, dashboard for X, 2×2 for X.
+    For cross-deal / institutional pages (sector landscape, market map, thesis) use
+    "llama wiki save <slug> --file ..." instead — see "Wiki" above.
+  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
@@ -1248,27 +1355,75 @@ https://command.llamaventures.vc/settings/tokens, run
   }
 
   // ----- Wiki: save (create or update) -----
+  // Two body modes:
+  //   --content "..."  inline markdown OR raw HTML (string)
+  //   --file <path>    read body from a file; if .html/.htm,
+  //                    content_type auto-detects to 'html'
+  // --content-type <markdown|html> overrides auto-detect.
+  // Refuses content_type mismatch on existing entries (server-side check;
+  // CLI surfaces the server error verbatim).
   if (area === "wiki" && action === "save") {
     const { flags, positional } = parseFlags(rest);
     const slug = positional[0];
     const title = flags.title;
-    const content = flags.content;
+    const inlineContent = flags.content;
+    const filePath = flags.file;
     const sourcesRaw = flags.sources;
-    if (!slug || !title || !content || !sourcesRaw) {
+    if (!slug || !title || !sourcesRaw || (!inlineContent && !filePath)) {
       throw new Error(
-        `Usage: llama wiki save <slug> --title "..." --content "..." --sources "url1;url2" [--type company] [--related "A;B"] [--lang en|zh]`
+        `Usage:
+  llama wiki save <slug> --title "..." --content "..." --sources "url1;url2" [--type company] [--related "A;B"] [--lang en|zh] [--content-type markdown|html]
+or
+  llama wiki save <slug> --title "..." --file path/to/article.{md,html} --sources "url1;url2" [--type company] [--related "A;B"] [--lang en|zh] [--content-type markdown|html]
+
+Pass either --content (inline) or --file (read from disk). With --file, content_type auto-detects from extension (.html/.htm → html, else markdown). Use --content-type to override.
+
+Routing — is this the right command?
+  ✓ Cross-deal / institutional knowledge (sector landscape, market map, thesis, framework, methodology)
+      → YES, you're in the right place.
+  ✗ Deal-specific HTML (IC memo for X, dashboard for X, 2×2 for one company)
+      → use \`llama html upload <dealId> --new --title "..." --file <path>\` instead.
+  ✗ Founder-facing public share link
+      → escape to Netlify only when the user explicitly says "share publicly" / "give it to the founder";
+        Llama Command outranks Netlify for everything internal.`
       );
     }
+    if (inlineContent && filePath) {
+      throw new Error("Pass either --content OR --file, not both.");
+    }
+    // Read body — either inline or from file.
+    let body;
+    let inferredType = "markdown";
+    if (filePath) {
+      const { readFileSync } = await import("fs");
+      body = readFileSync(String(filePath), "utf-8");
+      const lower = String(filePath).toLowerCase();
+      if (lower.endsWith(".html") || lower.endsWith(".htm")) {
+        inferredType = "html";
+      }
+    } else {
+      body = String(inlineContent);
+    }
+    // Determine content_type: explicit flag wins over file-extension inference.
+    let contentType = inferredType;
+    if (flags["content-type"]) {
+      const v = String(flags["content-type"]).toLowerCase();
+      if (v !== "markdown" && v !== "html") {
+        throw new Error(`--content-type must be 'markdown' or 'html', got "${v}"`);
+      }
+      contentType = v;
+    }
     const splitCsv = (v) => String(v).split(/[;|]/).map((s) => s.trim()).filter(Boolean);
     const payload = {
       slug,
       title: String(title),
-      content: String(content),
+      content: body,
       sources: splitCsv(sourcesRaw),
       type: flags.type ? String(flags.type) : undefined,
       related: flags.related ? splitCsv(flags.related) : undefined,
       lang: flags.lang === "zh" ? "zh" : "en",
       status: flags.status ? String(flags.status) : undefined,
+      content_type: contentType,
     };
     print(await request("POST", "/api/wiki/save", payload));
     return;
@@ -1954,15 +2109,180 @@ https://command.llamaventures.vc/settings/tokens, run
       const dealId = rest[0];
       if (!dealId) {
         throw new Error(
-          "Usage: llama html upload <dealId> --file PATH [--doc SLUG] [--assets DIR] [--source cli|agent]\n" +
-            "       echo '<!doctype html>...' | llama html upload <dealId> --stdin [--doc SLUG]",
+          "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.\n" +
+            "\n" +
+            "Routing — is this the right command?\n" +
+            "  ✓ DEAL-specific HTML (IC memo for X, dashboard for X, 2×2 for X)\n" +
+            "      → YES, you're in the right place. Pass <dealId> + --new / --doc.\n" +
+            "  ✗ Cross-deal / institutional knowledge (sector landscape, market map,\n" +
+            "    thesis, framework, methodology, anything not tied to one company)\n" +
+            "      → use `llama wiki save <slug> --title \"...\" --file <path>.html --sources \"...\"`\n" +
+            "        instead (renders at /wiki/<slug>).\n" +
+            "  ✗ Founder-facing public share link\n" +
+            "      → escape to Netlify only when the user explicitly says \"share publicly\";\n" +
+            "        Llama Command outranks Netlify for everything internal.",
         );
       }
-      const { flags } = parseFlags(rest.slice(1));
-      const slug =
+      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()
-          : "main";
+          : 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");
@@ -1992,6 +2312,7 @@ https://command.llamaventures.vc/settings/tokens, run
         });
         print({
           ok: true,
+          mode,
           document_slug: slug,
           version: data?.version,
           bytes: data?.bytes ?? Buffer.byteLength(html, "utf8"),
@@ -2104,6 +2425,7 @@ https://command.llamaventures.vc/settings/tokens, run
       }
       print({
         ok: true,
+        mode,
         document_slug: slug,
         version: body.version,
         asset_count: body.asset_count,

package/package.json

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