@llamaventures/cli 1.8.0 → 1.9.1

package/AGENT_BRIEFING.md

@@ -11,6 +11,15 @@ You are not just an AI assistant. You're an **extension of a team member** — w
 - **Be direct, terse, action-oriented.** Save your words for the genuine judgment calls.
 - **Critical when thinking, helpful when executing.** Push back on weak logic, then ship the work cleanly.
 
+## Onboard the human (teach as you go)
+
+Most teammates don't know everything this CLI can do. Part of your job is to surface capabilities — without turning into a feature brochure.
+
+- **First substantive interaction:** in one or two lines, point at the 2-3 capabilities most relevant to what they're doing right now, then do the work. Don't dump the whole command surface. (Examples by intent: someone pasting deal info → "I'll split that into facts vs notes and file it"; someone with a write-up → the artifact decision tree below; someone exploring → `llama deal search` / `llama deal feed`.)
+- **Teach in context, one line at a time.** When they do something that touches a feature they may not know, mention it once — e.g. after filing a fact: "Filed. `llama deal feed <id>` shows everything the team's added on this deal." Never more than one such aside per turn.
+- **Point at `llama --help`** for the full surface rather than reciting it. The CLI uses progressive help: `llama --help` is a short overview, `llama <area> --help` drills in.
+- **Stay current.** If you suspect the CLI is stale, run `llama version --check`; if it reports an upgrade, tell the user the one-line `npm i -g @llamaventures/cli@latest` command. Don't nag repeatedly.
+
 ## Pipeline First (hard rule)
 
 Any time the user mentions a company name or founder name:
@@ -95,6 +104,18 @@ HTML / thesis / artifact in hand
 
 **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."
 
+### Adding content to ONE deal — fact vs post vs brief (the #1 mis-route)
+
+These three look similar but land in different surfaces. Don't infer from the command name — pick by intent:
+
+| You want to… | Command | Lands in |
+|---|---|---|
+| Record a **sourced, verifiable fact** | `llama deal fact add <dealId> --category <cat> --claim "…" --source <url>` | Facts → deal **Feed** (FACT card) + citable in the **Memo** |
+| Leave a **comment / opinion / question / reaction** for the team | `llama post <dealId> "…"` (`@name` to notify) | Posts → deal **Feed** (POST card); `@mention` fires email + UI badge |
+| Write **narrative that belongs in the IC memo** | `llama brief add-text <dealId> --heading "…" --body "…"` | Brief blocks → **Memo tab only — NOT in the Feed** |
+
+⚠️ The trap: `brief add-text` is **not** visible in the Activity Feed. If the team should see it in the feed, use `llama post`. If it's a claim that needs a source + verification, use `llama deal fact add`. (It's `deal fact add`, not `fact-add`.)
+
 The table below details the exact CLI for each destination.
 
 | Type | Destination | How |
@@ -104,7 +125,7 @@ The table below details the exact CLI for each destination.
 | **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 (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. |
+| **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. **Native comments + working in-page (#) anchor links are injected automatically** — readers discuss inline and the table of contents scrolls; you don't wire anything up (pages that already embed the comment widget are left as-is). |
 | 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 |
 
@@ -293,7 +314,7 @@ the intake agent; relay the conversation, then surface the verdict.
 - This file: `AGENT_BRIEFING.md` in the `@llamaventures/cli` npm package
 - Re-printable any time: `llama agent-onboard`
 - MCP prompt: `agent_briefing` from the `llama-mcp` server
-- Public source: <https://github.com/SoujiOkita98/llama-cli/blob/main/AGENT_BRIEFING.md>
+- Public source: <https://github.com/Llama-Ventures/llama-cli/blob/main/AGENT_BRIEFING.md>
 
 You're now a Llama Ventures teammate (or an external agent helping a
 founder pitch us). Welcome.

package/README.md

@@ -13,7 +13,7 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@llamaventures/cli"><img alt="npm" src="https://img.shields.io/npm/v/@llamaventures/cli?label=npm&color=cb3837&logo=npm&logoColor=white"></a>
-  <a href="https://github.com/SoujiOkita98/llama-cli/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/SoujiOkita98/llama-cli/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://github.com/Llama-Ventures/llama-cli/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Llama-Ventures/llama-cli/actions/workflows/ci.yml/badge.svg"></a>
   <a href="https://docs.npmjs.com/trusted-publishers"><img alt="Provenance" src="https://img.shields.io/badge/provenance-signed-2e8b57?logo=npm"></a>
   <a href="https://nodejs.org/"><img alt="Node" src="https://img.shields.io/node/v/@llamaventures/cli?color=339933&logo=nodedotjs&logoColor=white"></a>
   <a href="https://modelcontextprotocol.io"><img alt="MCP 2024-11-05" src="https://img.shields.io/badge/MCP-2024--11--05-7d3aed"></a>

package/README.zh-CN.md

@@ -13,7 +13,7 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@llamaventures/cli"><img alt="npm" src="https://img.shields.io/npm/v/@llamaventures/cli?label=npm&color=cb3837&logo=npm&logoColor=white"></a>
-  <a href="https://github.com/SoujiOkita98/llama-cli/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/SoujiOkita98/llama-cli/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://github.com/Llama-Ventures/llama-cli/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Llama-Ventures/llama-cli/actions/workflows/ci.yml/badge.svg"></a>
   <a href="https://docs.npmjs.com/trusted-publishers"><img alt="Provenance" src="https://img.shields.io/badge/provenance-signed-2e8b57?logo=npm"></a>
   <a href="https://nodejs.org/"><img alt="Node" src="https://img.shields.io/node/v/@llamaventures/cli?color=339933&logo=nodedotjs&logoColor=white"></a>
   <a href="https://modelcontextprotocol.io"><img alt="MCP 2024-11-05" src="https://img.shields.io/badge/MCP-2024--11--05-7d3aed"></a>

package/bin/llama.mjs

@@ -30,6 +30,7 @@ import {
 } from "../lib/external.mjs";
 import { LLAMA_CLI_CLIENT_ID, pkceLoopbackFlow, revokeToken as revokeOAuthToken } from "../lib/oauth-flow.mjs";
 import { deleteBundle, detectBackend, readBundle, writeBundle } from "../lib/oauth-storage.mjs";
+import { maybeNudgeUpdate, getUpdateNudge } from "../lib/version-check.mjs";
 
 function parseFlags(args, knownFlags = null) {
   const flags = {};
@@ -348,6 +349,7 @@ Wiki:
   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)
+      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.
   Delete / restore (soft — reversible):
@@ -763,6 +765,14 @@ async function main() {
     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`);
+      return;
+    }
     console.log(version);
     return;
   }
@@ -775,6 +785,14 @@ async function main() {
     usage(area);
     return;
   }
+  // `llama <area> <action> --help` (e.g. `brief add-text --help`). Without this
+  // short-circuit, "--help" falls through to the action handler, where rest[0]
+  // can be read as a positional (e.g. dealId="--help") and trigger a REAL write.
+  // Catch --help/-h anywhere in the sub-command args and print group help first.
+  if (rest.includes("--help") || rest.includes("-h")) {
+    usage(area);
+    return;
+  }
 
   // `llama agent-onboard` — print the bundled AGENT_BRIEFING.md so an AI
   // agent reads it once and internalises the Llama Ventures workflow
@@ -2633,7 +2651,12 @@ Routing — is this the right command?
   process.exitCode = 1;
 }
 
-main().catch((error) => {
-  console.error(`Error: ${error.message}`);
-  process.exit(1);
-});
+main()
+  // Soft, throttled, TTY-gated update nudge. Runs AFTER the command's own
+  // output and is awaited so the registry check completes before exit — but
+  // it can never fail the command (all errors swallowed internally).
+  .then(() => maybeNudgeUpdate())
+  .catch((error) => {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  });

package/lib/client.mjs

@@ -38,7 +38,7 @@ export function readBriefing() {
       "AGENT_BRIEFING.md not found at " +
       briefingPath +
       ". This shouldn't happen in a published @llamaventures/cli install — " +
-      "report at https://github.com/SoujiOkita98/llama-cli/issues."
+      "report at https://github.com/Llama-Ventures/llama-cli/issues."
     );
   }
 }

package/lib/version-check.mjs

@@ -0,0 +1,118 @@
+// Soft update nudge for @llamaventures/cli.
+//
+// Philosophy: minimal friction. We NEVER block a command and we NEVER spam.
+// The npm registry is the source of truth for "latest published", so we
+// query it directly — no llama-command changes, nothing to keep in sync.
+//
+// Friction controls, all of which must pass before we print anything:
+//   1. TTY-gated   — only nudge an interactive human (process.stdout.isTTY).
+//                    MCP server / piped output / CI → silent, so agents and
+//                    scripts never see noise that could corrupt parsed output.
+//   2. Throttled   — at most once per 24h, tracked by a timestamp file.
+//   3. stderr only — the nudge never touches stdout, so `llama ... | jq` etc
+//                    stay clean even in the rare case it does print.
+//   4. Best-effort — every error path (offline, registry down, parse fail) is
+//                    swallowed. A nudge must never break or delay a command.
+
+import fs from "fs";
+import path from "path";
+import { createRequire } from "module";
+import { TOKEN_DIR } from "./client.mjs";
+
+const REGISTRY_URL = "https://registry.npmjs.org/@llamaventures/cli/latest";
+const STAMP_FILE = path.join(TOKEN_DIR, ".update-check");
+const THROTTLE_MS = 24 * 60 * 60 * 1000; // once per day
+const FETCH_TIMEOUT_MS = 2000;
+
+function installedVersion() {
+  try {
+    const requireFromHere = createRequire(import.meta.url);
+    return requireFromHere("../package.json").version;
+  } catch {
+    return null;
+  }
+}
+
+// Compare two semver strings. Returns true if `latest` is strictly newer than
+// `current`. Pre-release tags are ignored (we only ship plain x.y.z).
+function isNewer(latest, current) {
+  const a = String(latest).split(".").map((n) => parseInt(n, 10));
+  const b = String(current).split(".").map((n) => parseInt(n, 10));
+  for (let i = 0; i < 3; i++) {
+    const x = a[i] || 0;
+    const y = b[i] || 0;
+    if (x > y) return true;
+    if (x < y) return false;
+  }
+  return false;
+}
+
+function checkedRecently() {
+  try {
+    const last = parseInt(fs.readFileSync(STAMP_FILE, "utf8").trim(), 10);
+    return Number.isFinite(last) && Date.now() - last < THROTTLE_MS;
+  } catch {
+    return false;
+  }
+}
+
+function touchStamp() {
+  try {
+    fs.mkdirSync(TOKEN_DIR, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(STAMP_FILE, `${Date.now()}\n`, { mode: 0o600 });
+  } catch {
+    // Best-effort. If we can't write the stamp we may nudge again tomorrow —
+    // harmless. Never throw.
+  }
+}
+
+async function fetchLatest() {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    // The /latest convenience endpoint returns full JSON under the default
+    // Accept. (The abbreviated "vnd.npm.install-v1+json" metadata type is only
+    // valid on the full packument endpoint — it 406s here.)
+    const res = await fetch(REGISTRY_URL, { signal: controller.signal });
+    if (!res.ok) return null;
+    const data = await res.json();
+    return typeof data?.version === "string" ? data.version : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Compute the nudge line without any side effects (no TTY/throttle gating).
+ * Returns the one-line string if an upgrade is available, else null. Used by
+ * the explicit `llama version --check` command so an agent can surface it.
+ */
+export async function getUpdateNudge() {
+  const current = installedVersion();
+  if (!current) return null;
+  const latest = await fetchLatest();
+  if (!latest || !isNewer(latest, current)) return null;
+  return `⬆ llama CLI ${current} → ${latest} available · npm i -g @llamaventures/cli@latest`;
+}
+
+/**
+ * Fire-and-forget soft nudge for interactive humans. Safe to call without
+ * awaiting; resolves to true if it printed a nudge, false otherwise. Honors
+ * all four friction controls above. Set $LLAMA_NO_UPDATE_CHECK=1 to disable.
+ */
+export async function maybeNudgeUpdate() {
+  try {
+    if (process.env.LLAMA_NO_UPDATE_CHECK) return false;
+    if (!process.stdout.isTTY) return false; // humans only
+    if (checkedRecently()) return false;
+    touchStamp(); // stamp before the network call so a slow/failed check still throttles
+    const nudge = await getUpdateNudge();
+    if (!nudge) return false;
+    process.stderr.write(`${nudge}\n`);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llamaventures/cli",
-  "version": "1.8.0",
+  "version": "1.9.1",
   "description": "CLI + MCP server for the Llama Ventures investment workbench (command.llamaventures.vc).",
   "type": "module",
   "bin": {
@@ -18,13 +18,13 @@
     "node": ">=18"
   },
   "license": "MIT",
-  "homepage": "https://github.com/SoujiOkita98/llama-cli#readme",
+  "homepage": "https://github.com/Llama-Ventures/llama-cli#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/SoujiOkita98/llama-cli.git"
+    "url": "git+https://github.com/Llama-Ventures/llama-cli.git"
   },
   "bugs": {
-    "url": "https://github.com/SoujiOkita98/llama-cli/issues"
+    "url": "https://github.com/Llama-Ventures/llama-cli/issues"
   },
   "keywords": [
     "llama-ventures",
@@ -39,7 +39,7 @@
     "anthropic"
   ],
   "author": "Llama Ventures, Inc.",
-  "funding": "https://github.com/SoujiOkita98/llama-cli",
+  "funding": "https://github.com/Llama-Ventures/llama-cli",
   "publishConfig": {
     "access": "public"
   },