@llamaventures/cli 1.18.0 → 1.18.1

package/AGENT_BRIEFING.md

@@ -45,6 +45,7 @@ Any time the user mentions a company name or founder name:
    - Use `--status Outreached` when we only contacted/logged the company and have no response or effective relationship yet.
    - Use `--status Sourced` only once there is a response, intro, meeting, or another real relationship signal.
    - Also set `--source-direction Inbound` if the deal came into the firm; set `--source-direction Outbound` if Llama found/listed/reached out first.
+   - If assigning an owner at create time, use `--deal-owner` with an exact `/api/field-options` value, email, or user id. Do not guess from a first name.
 4. If user gives you new facts (status / valuation / founder note) → `llama deal update` immediately, tell the user **one line** afterward.
 
 Don't:
@@ -62,7 +63,7 @@ A teammate says "I just met them and heard…" or pastes a chunk of notes. Your
 
 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.
+   - **Verifiable claims → facts.** `llama deal fact add <dealId> --category <cat> --claim "…" --source "<where it came from>" --source-url <url>`. 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. In raw API terms, the fact text field is `claim` (`value` is only a compatibility alias), `source` is the human-readable provenance label, and `sourceUrl` is the canonical URL.
    - **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. **Read it back before you claim it's saved.** A tool call returning `{ok:true}` is NOT proof the content is where the user will look for it. After filing, run `llama deal feed <dealId>` and confirm your fact/note actually appears, THEN tell the user in plain language what you recorded and where. Never say "记好了 / saved" from the return value alone — the #1 failure is an agent writing to the wrong surface (e.g. the brief, which is the Memo and does NOT appear in the feed) and reporting success anyway. If it's not in the feed, you routed it wrong — fix it.
@@ -129,7 +130,7 @@ These three look similar but land in different surfaces. Don't infer from the co
 
 | 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** |
+| Record a **sourced, verifiable fact** | `llama deal fact add <dealId> --category <cat> --claim "…" --source "deck p3" --source-url <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** |
 
@@ -209,8 +210,8 @@ llama deal list [--owner ...] [--status ...]
 
 # Pipeline — write
 llama deal create "Company" --description "..." --source-direction Outbound --status Interested
-llama deal create "Company" --description "..." --source-direction Outbound --status Outreached
-llama deal create "Company" --description "..." --source-direction Inbound --status Sourced
+llama deal create "Company" --description "..." --source-direction Outbound --status Outreached --deal-owner "owner@llamaventures.vc"
+llama deal create "Company" --description "..." --source-direction Inbound --status Sourced --deal-owner "Exact Name"
 llama deal update <dealId> <field> <value>
 #   writable: status theirStage stage notes dealOwner source sourceDirection description website
 #             location founders proposedAmount roundSize valuation sector subsector

package/CHANGELOG.md

@@ -6,6 +6,14 @@ this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+## [1.18.1] - 2026-07-09
+
+### Changed
+- Clarified the Command facts write contract across CLI, MCP, and agent docs:
+  `claim` is canonical, `value` remains a compatibility alias, `sourceUrl`
+  round-trips as provenance, and categories are free text. `deal create` now
+  forwards `--deal-owner` using name, email, or user id.
+
 ## [1.18.0] - 2026-07-06
 
 ### Added
@@ -500,7 +508,8 @@ assistant-drafted (🤖) and enforces the AI trust ceiling.
 
 ---
 
-[Unreleased]: https://github.com/Llama-Ventures/llama-cli/compare/v1.18.0...HEAD
+[Unreleased]: https://github.com/Llama-Ventures/llama-cli/compare/v1.18.1...HEAD
+[1.18.1]: https://github.com/Llama-Ventures/llama-cli/compare/v1.18.0...v1.18.1
 [1.18.0]: https://github.com/Llama-Ventures/llama-cli/compare/v1.17.3...v1.18.0
 [1.17.3]: https://github.com/Llama-Ventures/llama-cli/compare/v1.17.2...v1.17.3
 [1.17.2]: https://github.com/Llama-Ventures/llama-cli/compare/v1.17.1...v1.17.2

package/README.md

@@ -96,7 +96,8 @@ llama deal show <dealId>
 llama deal feed <dealId>               # every contribution, newest first
 llama activity new-deals --since 24h   # recent deal creations
 llama activity updated-deals --since 7d # meaningful updates grouped by deal
-llama deal create "Acme AI" --source alex --source-direction Outbound --status Interested
+llama deal create "Acme AI" --source alex --deal-owner owner@llamaventures.vc --source-direction Outbound --status Interested
+llama deal fact add <dealId> --category funding --claim "Raised a seed round" --source "deck p3" --source-url https://...
 llama deal update <dealId> status Diligence
 llama post <dealId> "note body"
 llama brief add-text <dealId> --heading "..." --body "..."
@@ -111,6 +112,11 @@ Status vocabulary — `Interested`: tracked before any contact ·
 signal exists. `sourceDirection` is separate: `Inbound` came to the firm,
 `Outbound` we reached out first.
 
+Facts use `claim` for the fact text. `source` is a readable provenance label
+and `sourceUrl` is the canonical evidence URL; both round-trip from the API.
+For deal owners, use an exact `/api/field-options` `dealOwner` value, a user
+email, or a numeric user id.
+
 Run `llama --help` for the group index, `llama help all` for the full
 reference (100+ commands). Deletes are soft and audit-logged everywhere.
 

package/README.zh-CN.md

@@ -118,7 +118,8 @@ llama deal show <dealId>
 llama deal feed <dealId>               # 该 deal 的全部贡献，最新在前
 llama activity new-deals --since 24h   # 最近新建的 deal
 llama activity updated-deals --since 7d # 按 deal 聚合的实质更新
-llama deal create "Acme AI" --source alex --source-direction Outbound --status Interested
+llama deal create "Acme AI" --source alex --deal-owner owner@llamaventures.vc --source-direction Outbound --status Interested
+llama deal fact add <dealId> --category funding --claim "Raised a seed round" --source "deck p3" --source-url https://...
 llama deal update <dealId> status Diligence
 llama post <dealId> "备注内容"
 llama brief add-text <dealId> --heading "..." --body "..."
@@ -132,6 +133,10 @@ Status 语义——`Interested`：接触前先记录关注 · `Outreached`：已
 尚无回应 · `Sourced`：已有真实关系信号。`sourceDirection` 是独立维度：
 `Inbound` 流入，`Outbound` 我们主动。
 
+Facts 的正文用 `claim`。`source` 是人可读来源标签，`sourceUrl` 是 canonical
+证据 URL；两者都会从 API 回显。`dealOwner` 请用 `/api/field-options`
+里的精确 `dealOwner` 值、用户邮箱，或数字 user id。
+
 `llama --help` 看分组索引，`llama help all` 看全部 100+ 命令。
 所有删除默认软删除、有审计记录。
 

package/bin/llama-mcp.mjs

@@ -471,7 +471,11 @@ server.registerTool(
         .describe(
           "Our Stage workflow position. Use Interested when we want to record/track before contact; use Outreached when we contacted/logged them and have no response/effective relationship; use Sourced only once there is a response, intro, meeting, or other real relationship signal."
         ),
-      source: z.string().optional().describe("free-form sourced-by; recommend nominating a user"),
+      source: z.string().optional().describe("free-form sourced-by; exact team-member names also attach source_user_id"),
+      dealOwner: z
+        .string()
+        .optional()
+        .describe("owner override. Use an exact /api/field-options dealOwner value, a user email, or numeric user id."),
       sourceDirection: z
         .string()
         .optional()
@@ -510,7 +514,7 @@ server.registerTool(
   {
     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 → " +
+      "category, a claim, a source/sourceUrl, a confidence, and a trust rung (unverified → " +
       "agent-verified → human-vouched → endorsed) plus who/what recorded it.",
     inputSchema: {
       dealId: z.string(),
@@ -530,13 +534,15 @@ server.registerTool(
       "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.",
+      "for having checked it. `source` is a human-readable provenance label; `sourceUrl` is a " +
+      "canonical URL that round-trips as sourceUrl/source_url. Category is free text; common " +
+      "values include 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')"),
+      sourceUrl: z.string().optional().describe("canonical URL for the evidence, if separate from source"),
       confidence: z.enum(["high", "medium", "low"]).optional(),
       attested: z
         .boolean()
@@ -544,11 +550,12 @@ server.registerTool(
         .describe("true → stored 'agent-verified'; false/omitted → 'unverified'. Answer honestly."),
     },
   },
-  async ({ dealId, category, claim, source, confidence, attested }) =>
+  async ({ dealId, category, claim, source, sourceUrl, confidence, attested }) =>
     callApi("POST", `/api/deals/${encodeURIComponent(dealId)}/facts`, {
       category,
       claim,
       source: source ?? "",
+      ...(sourceUrl ? { sourceUrl } : {}),
       confidence: confidence ?? "medium",
       attested: attested === true,
     })

package/bin/llama.mjs

@@ -424,7 +424,7 @@ auto-detects \`gcloud auth print-identity-token\` and uses Bearer auth.
 Manually-set \`llc_\` tokens are used as a fallback.
 
 Deals:
-  llama deal create "Company" --source <name> --source-direction Inbound|Outbound --description "..." --status Interested|Outreached|Sourced --website https://...
+  llama deal create "Company" --source <name> --deal-owner <name|email|userId> --source-direction Inbound|Outbound --description "..." --status Interested|Outreached|Sourced --website https://...
   llama deal show <dealId>
   llama deal feed <dealId>                                     # every contribution (facts + notes), human-typed or assistant-drafted, newest first
   llama deal update <dealId> <field> <value>
@@ -534,8 +534,8 @@ Deal soft-delete / restore / trash list:
   llama deal trash                                             # list deleted deals
 
 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] [--attested]
+  llama deal fact list <dealId>
+  llama deal fact add <dealId> --category <cat> --claim "<text>" [--source "..."] [--source-url <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):
@@ -1440,10 +1440,11 @@ async function main() {
   if (area === "deal" && action === "create") {
     const { flags, positional } = parseFlags(rest);
     const companyName = positional.join(" ").trim();
-    if (!companyName) throw new Error("Usage: llama deal create \"Company\" [--source Name]");
+    if (!companyName) throw new Error("Usage: llama deal create \"Company\" [--source Name] [--deal-owner name|email|userId]");
     const body = {
       companyName,
       source: flags.source,
+      dealOwner: flags.dealOwner || flags["deal-owner"],
       sourceDirection: flags.sourceDirection || flags["source-direction"],
       description: flags.description,
       website: flags.website,
@@ -1735,10 +1736,6 @@ async function main() {
   }
 
   // ----- Deal facts (AI-extracted or human-asserted, with verification) -----
-  // NOTE: server routes currently use session-only auth() — token-only
-  // callers will get 401 until /api/deals/:id/facts and
-  // /api/deals/:id/facts/:factId switch to authenticate(). CLI surface
-  // is forward-compatible.
   if (area === "deal" && action === "fact") {
     const sub = rest[0];
     const dealId = rest[1];
@@ -1754,10 +1751,12 @@ async function main() {
     }
 
     if (sub === "add") {
-      if (!flags.category || !flags.claim) {
+      const claim = flags.claim ?? flags.value;
+      const sourceUrl = flags["source-url"] ?? flags.sourceUrl;
+      if (!flags.category || !claim) {
         throw new Error(
           `Usage: llama deal fact add <dealId> --category <cat> --claim "<text>" ` +
-          `[--source <url>] [--confidence high|medium|low] [--attested]`
+          `[--source "..."] [--source-url <url>] [--confidence high|medium|low] [--attested]`
         );
       }
       // --attested: the caller takes responsibility that this is accurate
@@ -1765,8 +1764,9 @@ async function main() {
       // 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),
+        claim: String(claim),
         source: flags.source ? String(flags.source) : "",
+        ...(sourceUrl ? { sourceUrl: String(sourceUrl) } : {}),
         confidence: flags.confidence ? String(flags.confidence) : "medium",
         attested: flags.attested === true,
       }));

package/package.json

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