@llamaventures/cli 1.7.0 → 1.9.0

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:
@@ -29,6 +38,19 @@ Don't:
 
 Conversation produces value → that value flows somewhere. This is not optional.
 
+### When someone gives you info about a deal (the most common case)
+
+A teammate says "I just met them and heard…" or pastes a chunk of notes. Your job: get it into the right deal, in the right layer, and confirm it's right. Three steps:
+
+1. **Find the deal** — `llama deal search "<name>"` (Pipeline First). New name → offer to create it.
+2. **Split what they gave you into two kinds** — this is the whole data model:
+   - **Verifiable claims → facts.** `llama deal fact add <dealId> --category <cat> --claim "…" --source "<where it came from>"`. A claim someone *relayed* ("their ARR is $3M", "raised from a16z") is a fact at **unverified** trust — it's hearsay until checked. Pass `--attested` ONLY if you actually verified it against a source yourself.
+   - **Their judgment / impression → a note.** `llama post <dealId> "…"`. "Founder seemed evasive", "I'd lean pass", "worth a second meeting" — opinion, not fact. Attributed, never "verified".
+   - A pasted blob → pull the verifiable claims out as facts, capture their take as a note.
+3. **Confirm accuracy.** After filing, tell them in plain language what you recorded and where, and ask if it's right. Facts you add stay **unverified** until a human confirms them (then they rise to human-vouched) — the confirmation IS the trust step. Never silently mark something verified.
+
+Why split it: facts and opinions live in different layers so the deal keeps one clean **source of truth** (facts, sourced + trust-rated) separate from people's **takes** (notes). The four layers — facts / notes / brief (AI's synthesis) / timeline — are documented in Llama Command's `docs/SCHEMA.md`.
+
 ### 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.

package/bin/llama-mcp.mjs

@@ -303,6 +303,22 @@ server.registerTool(
     callApi("GET", `/api/deals/${encodeURIComponent(dealId)}/blocks`)
 );
 
+server.registerTool(
+  "deal_feed",
+  {
+    description:
+      "The unified, time-sorted stream of everything a HUMAN has added to a deal — " +
+      "facts + notes/discussion + legacy posts, merged at query time, newest first. " +
+      "Excludes AI-generated content. Each item: kind (fact|note), ts, who, text, " +
+      "and for facts: source + trust rung + category.",
+    inputSchema: {
+      dealId: z.string(),
+    },
+  },
+  async ({ dealId }) =>
+    callApi("GET", `/api/deals/${encodeURIComponent(dealId)}/feed`)
+);
+
 server.registerTool(
   "brief_add_text",
   {

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 = {};
@@ -198,8 +199,7 @@ async function searchDeals(q, flags) {
   return result;
 }
 
-function usage() {
-  console.log(`Llama Command CLI
+const HELP_FULL = `Llama Command CLI
 
 Agent onboarding (run once on first install):
   llama agent-onboard                  # print AGENT_BRIEFING.md — the workflow contract for AI agents
@@ -225,6 +225,7 @@ Manually-set \`llc_\` tokens are used as a fallback.
 Deals:
   llama deal create "Company" --source <name> --description "..." --website https://...
   llama deal show <dealId>
+  llama deal feed <dealId>                                     # everything humans added (facts + notes), newest first
   llama deal update <dealId> <field> <value>
       Writable fields: status, theirStage, stage, notes, dealOwner, source,
       description, website, location, founders, proposedAmount, roundSize,
@@ -410,7 +411,86 @@ Token discovery (in order):
 Env:
   LLAMA_TOKEN    token override
   LLAMA_API_URL  API base URL override
-`);
+`;
+
+// ── Progressive help (Constitution §1) ──
+// Default `llama` / `llama --help` prints a SHORT root: the command groups +
+// a few starters. Drill into one group with `llama help <area>` (or
+// `llama <area> --help`); `llama help all` prints the full reference above.
+const HELP_ROOT = `Llama Command CLI — the \`llama\` command for the Llama Ventures workbench.
+
+Common:
+  llama deal search "<name>"        find a deal in the pipeline
+  llama deal show <dealId>          full deal record
+  llama deal feed <dealId>          everything humans added, newest first
+  llama post <dealId> "..."         add a note to a deal
+  llama agent-onboard               print the AI-agent workflow contract
+
+Command groups — run \`llama help <group>\` for that group's commands:
+  deal        create · show · feed · update · search · collaborators · links · delete
+  brief       brief blocks: list · add · edit · history · refresh
+  facts       deal facts + skill corrections (the sourced, trust-rated layer)
+  timeline    timeline · posts · mentions
+  wiki        cross-deal knowledge entries (markdown or HTML)
+  memo        long-form HTML investment memo
+  html        deal-specific HTML artifacts (/deals/<id>/browse/<slug>)
+  pitch       external founder intake (no token needed)
+  ownership   claim · nominate · approvals
+  admin       audit events (system admin only)
+  auth        setup · tokens · auth status
+
+  llama help all     the full command reference (everything at once)
+
+Auth: if you've run \`gcloud auth login\` with your @llamaventures.vc account,
+the CLI auto-detects it — no token needed (\`llc_\` tokens are a fallback).`;
+
+// Area → which top-level sections of HELP_FULL belong to it.
+const HELP_AREA_MATCH = {
+  deal: [/^Deals/, /^Collaborators/, /^Soft-delete/, /^Deal links/, /^Deal soft-delete/],
+  brief: [/^Brief blocks/, /^Brief \/ persona/],
+  facts: [/^Deal facts/, /^Skill corrections/],
+  timeline: [/^Timeline/, /^Mentions/],
+  wiki: [/^Wiki/, /^Where does this HTML/],
+  memo: [/^Memo/],
+  html: [/^Deal page HTML/],
+  pitch: [/^External pitch/],
+  ownership: [/^Ownership/, /^Approvals/],
+  admin: [/^Admin/],
+  auth: [/^Setup/, /^Zero-config/, /^Token discovery/, /^Env/],
+};
+
+// Slice HELP_FULL into sections: a top-level (non-indented) header line plus
+// the indented/blank lines that follow it, until the next header.
+function helpSections() {
+  const out = [];
+  let cur = null;
+  for (const line of HELP_FULL.split("\n")) {
+    if (/^[A-Za-z]/.test(line)) {
+      cur = { head: line, lines: [line] };
+      out.push(cur);
+    } else if (cur) {
+      cur.lines.push(line);
+    }
+  }
+  return out;
+}
+
+function usage(area) {
+  if (area === "all") {
+    console.log(HELP_FULL);
+    return;
+  }
+  const matchers = area && HELP_AREA_MATCH[area];
+  if (matchers) {
+    const blocks = helpSections()
+      .filter((s) => matchers.some((re) => re.test(s.head)))
+      .map((s) => s.lines.join("\n").replace(/\s+$/, ""));
+    if (blocks.length) {
+      console.log(blocks.join("\n\n"));
+      return;
+    }
+  }
+  console.log(HELP_ROOT);
 }
 
 // ============================================================
@@ -684,11 +764,24 @@ 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;
   }
   if (!area || area === "help" || area === "--help" || area === "-h") {
-    usage();
+    usage(area === "help" ? action : undefined);
+    return;
+  }
+  // `llama <area> --help` / `-h` → just that group's commands
+  if (action === "--help" || action === "-h") {
+    usage(area);
     return;
   }
 
@@ -978,6 +1071,13 @@ https://command.llamaventures.vc/settings/tokens, run
     return;
   }
 
+  if (area === "deal" && action === "feed") {
+    const dealId = rest[0];
+    if (!dealId) throw new Error("Usage: llama deal feed <dealId>");
+    print(await request("GET", `/api/deals/${encodeURIComponent(dealId)}/feed`));
+    return;
+  }
+
   if (area === "deal" && action === "update") {
     const [dealId, field, ...valueParts] = rest;
     const value = valueParts.join(" ");
@@ -2542,7 +2642,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/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.7.0",
+  "version": "1.9.0",
   "description": "CLI + MCP server for the Llama Ventures investment workbench (command.llamaventures.vc).",
   "type": "module",
   "bin": {