@llamaventures/cli 1.6.1 → 1.8.0

package/AGENT_BRIEFING.md

@@ -29,6 +29,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.
@@ -157,6 +170,9 @@ llama deal list [--owner ...] [--status ...]
 # Pipeline — write
 llama deal create "Company" --description "..."
 llama deal update <dealId> <field> <value>
+#   writable: status theirStage stage notes dealOwner source description website
+#             location founders proposedAmount roundSize valuation sector subsector
+#             foundedYear leadInvestor investors   (each write logs a deal_events row)
 
 # Brief blocks
 llama brief blocks <dealId>
@@ -244,6 +260,7 @@ You can also fetch this exact briefing as an MCP prompt named `agent_briefing`.
 ## Boundaries (what NOT to do)
 
 - **Don't impersonate a human's opinion.** Tag AI-generated content as `[AI · …]`.
+- **Don't vouch for facts you haven't checked.** When you `add fact`, pass `--attested` only if you actually verified the claim against its source. Without it the fact is stored as *unverified* — that's the honest default, not a failure. You cannot mark a fact as human-confirmed; only a person can raise it there.
 - **Don't use absolute language** ("only", "all", "best", "no one", "极") unless verifiable.
 - **Don't bypass `llama` CLI / MCP for pipeline writes.** CSRF defence, rate limits, audit logs all flow through it.
 - **Don't write to retired surfaces.** Google Sheet is read-only archive. Legacy `~/.llama-command/config.json` auto-migrates.

package/bin/llama-mcp.mjs

@@ -197,7 +197,8 @@ server.registerTool(
     description:
       "Update a single whitelisted field on a deal. Writable fields: status, theirStage, " +
       "notes, stage, dealOwner, source, description, website, location, founders, " +
-      "proposedAmount, roundSize, valuation. Logs a field_change event in deal_events.",
+      "proposedAmount, roundSize, valuation, sector, subsector, foundedYear, leadInvestor, " +
+      "investors. Logs a field_change event in deal_events.",
     inputSchema: {
       dealId: z.string(),
       field: z.string().describe("camelCase field name (see description for whitelist)"),
@@ -208,6 +209,82 @@ server.registerTool(
     callApi("POST", "/api/deals/update", { dealId, field, value })
 );
 
+// ============================================================
+// Deal facts (research substrate + trust ladder)
+// ============================================================
+
+server.registerTool(
+  "deal_fact_list",
+  {
+    description:
+      "List a deal's recorded facts (the research substrate). Each fact carries a " +
+      "category, a claim, a source, a confidence, and a trust rung (unverified → " +
+      "agent-verified → human-vouched → endorsed) plus who/what recorded it.",
+    inputSchema: {
+      dealId: z.string(),
+    },
+  },
+  async ({ dealId }) =>
+    callApi("GET", `/api/deals/${encodeURIComponent(dealId)}/facts`)
+);
+
+server.registerTool(
+  "deal_fact_add",
+  {
+    description:
+      "Record a factual claim about a deal. RESPONSIBILITY: set `attested` honestly — " +
+      "true ONLY if you actually verified the claim against its cited source (the fact " +
+      "is then stored at trust level 'agent-verified'); false/omitted if you are relaying " +
+      "something unconfirmed (stored 'unverified', which is the honest default). You CANNOT " +
+      "mark a fact as human-confirmed — only a person can raise it to 'human-vouched'. " +
+      "`confidence` is how certain the claim is; `attested` is whether YOU take responsibility " +
+      "for having checked it. category ∈ founders | financials | product | market | team | " +
+      "company_basics | risk | fundraise | milestone | meta.",
+    inputSchema: {
+      dealId: z.string(),
+      category: z.string(),
+      claim: z.string(),
+      source: z.string().optional().describe("where you found this (URL, 'deck p3', 'LinkedIn')"),
+      confidence: z.enum(["high", "medium", "low"]).optional(),
+      attested: z
+        .boolean()
+        .optional()
+        .describe("true → stored 'agent-verified'; false/omitted → 'unverified'. Answer honestly."),
+    },
+  },
+  async ({ dealId, category, claim, source, confidence, attested }) =>
+    callApi("POST", `/api/deals/${encodeURIComponent(dealId)}/facts`, {
+      category,
+      claim,
+      source: source ?? "",
+      confidence: confidence ?? "medium",
+      attested: attested === true,
+    })
+);
+
+server.registerTool(
+  "deal_fact_verify",
+  {
+    description:
+      "Verify a recorded fact. status='confirmed' vouches for it (raises to 'human-vouched'); " +
+      "status='disputed' marks it contradicted. Trust-ladder guardrails apply server-side " +
+      "(external-org callers are capped at 'unverified'; only Partners reach 'endorsed'). " +
+      "Optionally pass correctedValue when disputing.",
+    inputSchema: {
+      dealId: z.string(),
+      factId: z.union([z.string(), z.number()]),
+      status: z.enum(["confirmed", "disputed"]),
+      correctedValue: z.string().optional(),
+    },
+  },
+  async ({ dealId, factId, status, correctedValue }) =>
+    callApi(
+      "PATCH",
+      `/api/deals/${encodeURIComponent(dealId)}/facts/${encodeURIComponent(String(factId))}`,
+      { status, ...(correctedValue !== undefined ? { correctedValue } : {}) }
+    )
+);
+
 // ============================================================
 // Brief blocks
 // ============================================================
@@ -226,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",
   {
@@ -272,6 +365,108 @@ server.registerTool(
     addBriefBlock(dealId, { type: "callout", tone, heading: heading ?? "", body })
 );
 
+server.registerTool(
+  "brief_edit",
+  {
+    description:
+      "Edit an existing brief block in place. Pass only the fields you want to change " +
+      "(heading/body/url/label/description/tone). Meta toggles: locked (protect from bulk " +
+      "overwrite), hidden (fold), sourceSection (route watcher writes). Snapshots the prior " +
+      "version to history (reversible via brief_restore_version).",
+    inputSchema: {
+      dealId: z.string(),
+      blockId: z.string(),
+      heading: z.string().optional(),
+      body: z.string().optional(),
+      url: z.string().optional(),
+      label: z.string().optional(),
+      description: z.string().optional(),
+      tone: z.string().optional(),
+      locked: z.boolean().optional(),
+      hidden: z.boolean().optional(),
+      sourceSection: z.string().optional(),
+    },
+  },
+  async ({ dealId, blockId, heading, body, url, label, description, tone, locked, hidden, sourceSection }) => {
+    const patch = {};
+    for (const [k, v] of Object.entries({ heading, body, url, label, description, tone })) {
+      if (v !== undefined) patch[k] = v;
+    }
+    const meta = {};
+    if (locked !== undefined) meta.locked = locked;
+    if (hidden !== undefined) meta.hidden = hidden;
+    if (sourceSection !== undefined) meta.sourceSection = sourceSection;
+    if (Object.keys(meta).length > 0) patch.meta = meta;
+    return callApi(
+      "PATCH",
+      `/api/deals/${encodeURIComponent(dealId)}/blocks/${encodeURIComponent(blockId)}`,
+      patch
+    );
+  }
+);
+
+server.registerTool(
+  "brief_delete",
+  {
+    description:
+      "Soft-delete a brief block (reversible via brief_restore). Locked blocks are refused.",
+    inputSchema: { dealId: z.string(), blockId: z.string() },
+  },
+  async ({ dealId, blockId }) =>
+    callApi("DELETE", `/api/deals/${encodeURIComponent(dealId)}/blocks/${encodeURIComponent(blockId)}`)
+);
+
+server.registerTool(
+  "brief_restore",
+  {
+    description: "Restore a soft-deleted brief block.",
+    inputSchema: { dealId: z.string(), blockId: z.string() },
+  },
+  async ({ dealId, blockId }) =>
+    callApi("POST", `/api/deals/${encodeURIComponent(dealId)}/blocks/${encodeURIComponent(blockId)}/restore`)
+);
+
+server.registerTool(
+  "brief_history",
+  {
+    description:
+      "List the content-version history of a brief block (every overwrite is snapshotted). " +
+      "Use the returned history id with brief_restore_version.",
+    inputSchema: {
+      dealId: z.string(),
+      blockId: z.string(),
+      limit: z.number().optional(),
+    },
+  },
+  async ({ dealId, blockId, limit }) => {
+    const qs = limit ? `?limit=${encodeURIComponent(String(limit))}` : "";
+    return callApi(
+      "GET",
+      `/api/deals/${encodeURIComponent(dealId)}/blocks/${encodeURIComponent(blockId)}/history${qs}`
+    );
+  }
+);
+
+server.registerTool(
+  "brief_restore_version",
+  {
+    description:
+      "Restore a brief block to a specific historical version (find historyId via brief_history). " +
+      "Itself reversible — the outgoing version is snapshotted before replacement.",
+    inputSchema: {
+      dealId: z.string(),
+      blockId: z.string(),
+      historyId: z.number(),
+    },
+  },
+  async ({ dealId, blockId, historyId }) =>
+    callApi(
+      "POST",
+      `/api/deals/${encodeURIComponent(dealId)}/blocks/${encodeURIComponent(blockId)}/history`,
+      { history_id: historyId }
+    )
+);
+
 // ============================================================
 // Wiki (knowledge base)
 // ============================================================
@@ -482,6 +677,109 @@ server.registerTool(
   }
 );
 
+server.registerTool(
+  "mentions_resolve",
+  {
+    description: "Mark an @-mention as resolved (clears it from the recipient's open cues).",
+    inputSchema: { mentionId: z.union([z.string(), z.number()]) },
+  },
+  async ({ mentionId }) =>
+    callApi("POST", `/api/mentions/${encodeURIComponent(String(mentionId))}/resolve`)
+);
+
+// ============================================================
+// Skill corrections (persona-owner pushback workflow)
+// ============================================================
+
+server.registerTool(
+  "skill_correction_list",
+  {
+    description:
+      "List the recorded corrections (long-term rules) for a persona/skill. These shape how " +
+      "that persona's analysis is generated.",
+    inputSchema: {
+      skillSlug: z.string(),
+      includeDeleted: z.boolean().optional(),
+    },
+  },
+  async ({ skillSlug, includeDeleted }) => {
+    const params = new URLSearchParams({ skill: skillSlug });
+    if (includeDeleted) params.set("include_deleted", "1");
+    return callApi("GET", `/api/skill-corrections?${params}`);
+  }
+);
+
+server.registerTool(
+  "skill_correction_add",
+  {
+    description:
+      "Record a long-term correction rule for a persona/skill (e.g. 'always check burn multiple " +
+      "before commenting on efficiency'). ALWAYS reconfirm the distilled rule with the user before " +
+      "calling — this changes how the persona behaves going forward. Optionally tie it to the deal/" +
+      "block where it came up.",
+    inputSchema: {
+      skillSlug: z.string(),
+      correctionText: z.string(),
+      dealUuid: z.string().optional(),
+      blockId: z.string().optional(),
+    },
+  },
+  async ({ skillSlug, correctionText, dealUuid, blockId }) =>
+    callApi("POST", "/api/skill-corrections", {
+      skill_slug: skillSlug,
+      correction_text: correctionText,
+      triggered_in_deal_uuid: dealUuid ?? null,
+      triggered_in_block_id: blockId ?? null,
+    })
+);
+
+server.registerTool(
+  "skill_correction_delete",
+  {
+    description: "Soft-delete a recorded skill correction by id.",
+    inputSchema: { id: z.union([z.string(), z.number()]) },
+  },
+  async ({ id }) =>
+    callApi("DELETE", `/api/skill-corrections/${encodeURIComponent(String(id))}`)
+);
+
+// ============================================================
+// Brief / persona refresh (signal-driven re-evaluation)
+// ============================================================
+
+server.registerTool(
+  "deal_refresh_brief",
+  {
+    description:
+      "Trigger a stale-section re-evaluation of a deal's brief. Pass force=true to bypass the " +
+      "debounce. Returns a runId (or null if debounced / deal inactive).",
+    inputSchema: {
+      dealId: z.string(),
+      force: z.boolean().optional(),
+    },
+  },
+  async ({ dealId, force }) =>
+    callApi(
+      "POST",
+      `/api/deals/${encodeURIComponent(dealId)}/refresh-brief${force ? "?force=1" : ""}`
+    )
+);
+
+server.registerTool(
+  "deal_refresh_persona",
+  {
+    description:
+      "Regenerate one persona's analysis section for a deal. persona ∈ gavin | kyle | jack | " +
+      "david | bryan | herman | hongjiang | liuyi | kevin. Returns a runId (or null if debounced).",
+    inputSchema: {
+      dealId: z.string(),
+      persona: z.string(),
+    },
+  },
+  async ({ dealId, persona }) =>
+    callApi("POST", `/api/deals/${encodeURIComponent(dealId)}/refresh-persona`, { persona })
+);
+
 // ============================================================
 // External pitch (founder intake) — no Llama Command token required
 // ============================================================

package/bin/llama.mjs

@@ -198,8 +198,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,7 +224,15 @@ 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,
+      valuation, sector, subsector, foundedYear, leadInvestor, investors.
+      e.g.  llama deal update <dealId> website https://acme.ai
+            llama deal update <dealId> sector "Developer Tools"
+            llama deal update <dealId> foundedYear 2024
+            llama deal update <dealId> leadInvestor "Acme Capital"
   llama deal search <query> [--founder name] [--owner <user-key>] [--status Diligence]
                             [--theirStage Raising] [--stage Seed]
                             [--limit 200] [--offset 0]
@@ -307,7 +314,7 @@ Deal soft-delete / restore / trash list:
 
 Deal facts (AI-extracted or human-asserted, with verification):
   llama deal fact list <dealId>                                # ⚠ session-only on server today
-  llama deal fact add <dealId> --category <cat> --claim "<text>" [--source <url>] [--confidence high|medium|low]
+  llama deal fact add <dealId> --category <cat> --claim "<text>" [--source <url>] [--confidence high|medium|low] [--attested]
   llama deal fact verify <dealId> <factId> --status confirmed|disputed [--corrected-value "..."]
 
 Skill corrections (persona-owner pushback — read by persona-watcher):
@@ -403,7 +410,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);
 }
 
 // ============================================================
@@ -681,7 +767,12 @@ async function main() {
     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;
   }
 
@@ -971,6 +1062,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(" ");
@@ -1147,14 +1245,18 @@ https://command.llamaventures.vc/settings/tokens, run
       if (!flags.category || !flags.claim) {
         throw new Error(
           `Usage: llama deal fact add <dealId> --category <cat> --claim "<text>" ` +
-          `[--source <url>] [--confidence high|medium|low]`
+          `[--source <url>] [--confidence high|medium|low] [--attested]`
         );
       }
+      // --attested: the caller takes responsibility that this is accurate
+      // (verified against the source). With it, the fact is recorded as
+      // vouched; without it, it stays unverified. Declare honestly.
       print(await request("POST", `/api/deals/${encodeURIComponent(dealId)}/facts`, {
         category: String(flags.category),
         claim: String(flags.claim),
         source: flags.source ? String(flags.source) : "",
         confidence: flags.confidence ? String(flags.confidence) : "medium",
+        attested: flags.attested === true,
       }));
       return;
     }
@@ -2160,8 +2262,8 @@ Routing — is this the right command?
       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.
+      // Accept it as an alias for --doc so the earlier failure mode
+      // (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;

package/package.json

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