@llamaventures/cli 1.18.0 → 1.19.0

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,26 @@ this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+## [1.19.0] - 2026-07-16
+
+### Added
+- Pin each CLI artifact to the exact versioned Llama Core OpenAPI contract,
+  source commit, and complete source-derived operation inventory.
+- Verify the contract identity and required Core operations during tests,
+  packaging, clean tarball installation, and release-gate validation.
+
+### Changed
+- Treat Core HTTP as the CLI's only backend boundary and expose contract/build
+  provenance through `llama version --json` for independent rollback audits.
+
+## [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 +520,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

@@ -42,6 +42,7 @@
 ```bash
 npm i -g @llamaventures/cli    # Node 18+; also puts `llama-mcp` on your PATH
 llama --version
+llama version --json           # package, source commit, and pinned Core API contract
 llama auth status              # round-trips against /api/me
 ```
 
@@ -96,7 +97,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 +113,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

@@ -67,6 +67,7 @@ Pitch 完成后档案自动进我们团队的 inbox，我们会主动联系你
 ```bash
 npm i -g @llamaventures/cli    # Node 18+；llama-mcp 也会一起装上 PATH
 llama --version
+llama version --json           # 包版本、源码 commit 与固定的 Core API 契约
 llama auth status              # 会跑一次 /api/me 验证
 ```
 
@@ -118,7 +119,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 +134,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

@@ -35,6 +35,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";
 import { maybeNudgeUpdate, getUpdateNudge } from "../lib/version-check.mjs";
+import { getBuildInfo } from "../lib/build-info.mjs";
 
 const requireFromHere = createRequire(import.meta.url);
 const { version: PKG_VERSION } = requireFromHere("../package.json");
@@ -424,7 +425,8 @@ 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 founders set <dealId> --json '[{"name":"Ada","email":"ada@example.com","linkedin_url":"https://linkedin.com/in/ada"}]'
   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 +536,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):
@@ -1005,6 +1007,10 @@ async function runPitchRepl() {
 async function main() {
   const [area, action, ...rest] = process.argv.slice(2);
   if (area === "--version" || area === "-v" || area === "version") {
+    if (action === "--json" || action === "json") {
+      print(getBuildInfo());
+      return;
+    }
     // `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.
@@ -1440,10 +1446,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,
@@ -1483,6 +1490,26 @@ async function main() {
     return;
   }
 
+  if (area === "deal" && action === "founders") {
+    const sub = rest[0];
+    const dealId = rest[1];
+    const { flags } = parseFlags(rest.slice(2), ["json"]);
+    if (sub !== "set" || !dealId || typeof flags.json !== "string") {
+      throw new Error(
+        "Usage: llama deal founders set <dealId> --json '[{\"name\":\"Ada\",\"email\":\"ada@example.com\"}]'"
+      );
+    }
+    let founders;
+    try {
+      founders = JSON.parse(flags.json);
+    } catch {
+      throw new Error("--json must be a valid JSON array");
+    }
+    if (!Array.isArray(founders)) throw new Error("--json must be a JSON array");
+    print(await request("PUT", `/api/deals/${encodeURIComponent(dealId)}/founders`, { founders }));
+    return;
+  }
+
   // ----- deals.extra JSONB patches (system-admin only, server-gated) -----
   // Same endpoint as `deal update`, but `extraKey` instead of `field`.
   // Server patches one top-level key via jsonb_set and audits the change
@@ -1699,6 +1726,8 @@ async function main() {
       const linkId = rest[2];
       if (!linkId) throw new Error(`Usage: llama deal link ${sub} <dealId> <linkId>`);
       const path = `/api/deals/${encodeURIComponent(dealId)}/links/${encodeURIComponent(linkId)}`;
+      // @core-api-operation DELETE /api/deals/{dealId}/links/{linkId}
+      // @core-api-operation POST /api/deals/{dealId}/links/{linkId}/restore
       print(await request(
         sub === "delete" ? "DELETE" : "POST",
         sub === "delete" ? path : `${path}/restore`
@@ -1735,10 +1764,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 +1779,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 +1792,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,
       }));
@@ -1967,6 +1995,7 @@ async function main() {
     if (!slug) throw new Error("Usage: llama wiki read <slug> [--lang en|zh]");
     const lang = flags.lang === "zh" ? "zh" : "en";
     const path = `/api/wiki/${encodeURIComponent(slug)}?lang=${lang}`;
+    // @core-api-operation GET /api/wiki/{slug}
     print(await request("GET", path));
     return;
   }
@@ -2298,6 +2327,9 @@ Routing — is this the right command?
       if (flags["errors-only"]) params.set("errors_only", "1");
     }
     const qs = params.toString() ? `?${params.toString()}` : "";
+    // @core-api-operation GET /api/admin/auth-events
+    // @core-api-operation GET /api/admin/deal-events
+    // @core-api-operation GET /api/admin/agent-events
     print(await request("GET", `/api/admin/${sub}${qs}`));
     return;
   }

package/contracts/core-api.json

@@ -0,0 +1,9 @@
+{
+  "format": "llama.core-api-contract.v1",
+  "name": "llama-core-api",
+  "apiVersion": "1.0.1",
+  "openapiVersion": "3.0.3",
+  "sha256": "95ce3639aeee15b0fed09830116838f2a11fd2e40e4f35bf80d785664ecf8d96",
+  "pathCount": 211,
+  "operationCount": 273
+}

package/contracts/required-operations.json

@@ -0,0 +1,91 @@
+{
+  "format": "llama.cli-core-api-operations.v1",
+  "coreApiContract": "contracts/core-api.json",
+  "requiredOperations": [
+    { "method": "DELETE", "path": "/api/deals/{dealId}" },
+    { "method": "DELETE", "path": "/api/deals/{dealId}/blocks/{blockId}" },
+    { "method": "DELETE", "path": "/api/deals/{dealId}/collaborators/{userId}" },
+    { "method": "DELETE", "path": "/api/deals/{dealId}/documents/{slug}" },
+    { "method": "DELETE", "path": "/api/deals/{dealId}/documents/{slug}/html" },
+    { "method": "DELETE", "path": "/api/deals/{dealId}/links/{linkId}" },
+    { "method": "DELETE", "path": "/api/deals/{dealId}/memo" },
+    { "method": "DELETE", "path": "/api/skill-corrections/{id}" },
+    { "method": "DELETE", "path": "/api/wiki/{slug}" },
+    { "method": "GET", "path": "/api/admin/agent-events" },
+    { "method": "GET", "path": "/api/admin/auth-events" },
+    { "method": "GET", "path": "/api/admin/deal-events" },
+    { "method": "GET", "path": "/api/agent/activity" },
+    { "method": "GET", "path": "/api/agent/briefing" },
+    { "method": "GET", "path": "/api/agent/explain" },
+    { "method": "GET", "path": "/api/agent/manifest" },
+    { "method": "GET", "path": "/api/agent/skills" },
+    { "method": "GET", "path": "/api/agent/skills/{slug}" },
+    { "method": "GET", "path": "/api/deals" },
+    { "method": "GET", "path": "/api/deals/{dealId}" },
+    { "method": "GET", "path": "/api/deals/{dealId}/blocks" },
+    { "method": "GET", "path": "/api/deals/{dealId}/blocks/{blockId}" },
+    { "method": "GET", "path": "/api/deals/{dealId}/blocks/{blockId}/history" },
+    { "method": "GET", "path": "/api/deals/{dealId}/collaborators" },
+    { "method": "GET", "path": "/api/deals/{dealId}/command-center" },
+    { "method": "GET", "path": "/api/deals/{dealId}/documents" },
+    { "method": "GET", "path": "/api/deals/{dealId}/documents/{slug}/html" },
+    { "method": "GET", "path": "/api/deals/{dealId}/documents/{slug}/html/history" },
+    { "method": "GET", "path": "/api/deals/{dealId}/facts" },
+    { "method": "GET", "path": "/api/deals/{dealId}/feed" },
+    { "method": "GET", "path": "/api/deals/{dealId}/links" },
+    { "method": "GET", "path": "/api/deals/{dealId}/memo" },
+    { "method": "GET", "path": "/api/deals/{dealId}/timeline" },
+    { "method": "GET", "path": "/api/deals/deleted" },
+    { "method": "GET", "path": "/api/me" },
+    { "method": "GET", "path": "/api/me/nominations" },
+    { "method": "GET", "path": "/api/mentions" },
+    { "method": "GET", "path": "/api/mentions/unread-count" },
+    { "method": "GET", "path": "/api/oauth/authorize" },
+    { "method": "GET", "path": "/api/partner/approvals" },
+    { "method": "GET", "path": "/api/skill-corrections" },
+    { "method": "GET", "path": "/api/users" },
+    { "method": "GET", "path": "/api/wiki/{slug}" },
+    { "method": "GET", "path": "/api/wiki/search" },
+    { "method": "PATCH", "path": "/api/deals/{dealId}/blocks/{blockId}" },
+    { "method": "PATCH", "path": "/api/deals/{dealId}/documents/{slug}" },
+    { "method": "PATCH", "path": "/api/deals/{dealId}/facts/{factId}" },
+    { "method": "POST", "path": "/api/agent/client-events" },
+    { "method": "POST", "path": "/api/agent/eval-feedback" },
+    { "method": "POST", "path": "/api/deals/{dealId}/agent-runs/{runId}/revert" },
+    { "method": "POST", "path": "/api/deals/{dealId}/blocks/{blockId}/history" },
+    { "method": "POST", "path": "/api/deals/{dealId}/blocks/{blockId}/restore" },
+    { "method": "POST", "path": "/api/deals/{dealId}/collaborators" },
+    { "method": "POST", "path": "/api/deals/{dealId}/collaborators/{userId}/restore" },
+    { "method": "POST", "path": "/api/deals/{dealId}/documents" },
+    { "method": "POST", "path": "/api/deals/{dealId}/documents/{slug}/html/restore/{version}" },
+    { "method": "POST", "path": "/api/deals/{dealId}/enrich" },
+    { "method": "POST", "path": "/api/deals/{dealId}/facts" },
+    { "method": "POST", "path": "/api/deals/{dealId}/links" },
+    { "method": "POST", "path": "/api/deals/{dealId}/links/{linkId}/restore" },
+    { "method": "POST", "path": "/api/deals/{dealId}/memo" },
+    { "method": "POST", "path": "/api/deals/{dealId}/posts" },
+    { "method": "POST", "path": "/api/deals/{dealId}/propose-owner" },
+    { "method": "POST", "path": "/api/deals/{dealId}/refresh-brief" },
+    { "method": "POST", "path": "/api/deals/{dealId}/refresh-persona" },
+    { "method": "POST", "path": "/api/deals/{dealId}/restore" },
+    { "method": "POST", "path": "/api/deals/{dealId}/threads" },
+    { "method": "POST", "path": "/api/deals/{dealId}/threads/{threadId}" },
+    { "method": "POST", "path": "/api/deals/create" },
+    { "method": "POST", "path": "/api/deals/update" },
+    { "method": "POST", "path": "/api/external/chat" },
+    { "method": "POST", "path": "/api/external/start-session" },
+    { "method": "POST", "path": "/api/external/upload" },
+    { "method": "POST", "path": "/api/mentions/{id}/resolve" },
+    { "method": "POST", "path": "/api/nominations/{approvalId}" },
+    { "method": "POST", "path": "/api/oauth/revoke" },
+    { "method": "POST", "path": "/api/oauth/token" },
+    { "method": "POST", "path": "/api/partner/approvals" },
+    { "method": "POST", "path": "/api/skill-corrections" },
+    { "method": "POST", "path": "/api/wiki/{slug}/restore" },
+    { "method": "POST", "path": "/api/wiki/save" },
+    { "method": "PUT", "path": "/api/deals/{dealId}/blocks" },
+    { "method": "PUT", "path": "/api/deals/{dealId}/documents/{slug}/html" },
+    { "method": "PUT", "path": "/api/deals/{dealId}/founders" },
+    { "method": "PUT", "path": "/api/deals/{dealId}/memo" }
+  ]
+}

package/lib/build-info.mjs

@@ -0,0 +1,34 @@
+import { createRequire } from "node:module";
+
+const requireFromHere = createRequire(import.meta.url);
+
+function readJson(relativePath) {
+  try {
+    return requireFromHere(relativePath);
+  } catch {
+    return null;
+  }
+}
+
+export function getBuildInfo() {
+  const built = readJson("./build-manifest.json");
+  if (built) return built;
+
+  const packageJson = readJson("../package.json") || {};
+  const contract = readJson("../contracts/core-api.json") || {};
+  return {
+    format: "llama.cli-build.v1",
+    packageName: packageJson.name || "@llamaventures/cli",
+    packageVersion: packageJson.version || "unknown",
+    sourceSha: "local/unknown",
+    sourceKind: "local",
+    sourceDirty: null,
+    coreApiContract: {
+      format: contract.format || "unknown",
+      name: contract.name || "llama-core-api",
+      apiVersion: contract.apiVersion || "unknown",
+      openapiVersion: contract.openapiVersion || "unknown",
+      sha256: contract.sha256 || "unknown",
+    },
+  };
+}

package/lib/build-manifest.json

@@ -0,0 +1,15 @@
+{
+  "format": "llama.cli-build.v1",
+  "packageName": "@llamaventures/cli",
+  "packageVersion": "1.19.0",
+  "sourceSha": "5f615ca16d607fc0da09887952afdf42301a43f8",
+  "sourceKind": "github",
+  "sourceDirty": false,
+  "coreApiContract": {
+    "format": "llama.core-api-contract.v1",
+    "name": "llama-core-api",
+    "apiVersion": "1.0.1",
+    "openapiVersion": "3.0.3",
+    "sha256": "95ce3639aeee15b0fed09830116838f2a11fd2e40e4f35bf80d785664ecf8d96"
+  }
+}

package/lib/client.mjs

@@ -14,6 +14,7 @@ import { fileURLToPath } from "url";
 import { execFile as _execFile } from "child_process";
 import { promisify } from "util";
 import { createHash, randomUUID } from "crypto";
+import { getBuildInfo } from "./build-info.mjs";
 
 const execFile = promisify(_execFile);
 
@@ -207,9 +208,13 @@ function rememberAgentEvent(event) {
 }
 
 function agentClientHeaders(command) {
+  const build = getBuildInfo();
   return {
     "X-Llama-Client": runtimeClient,
     "X-Llama-Client-Version": getPackageVersion(),
+    "X-Llama-Client-Source-Sha": build.sourceSha,
+    "X-Llama-API-Contract-Version": build.coreApiContract.apiVersion,
+    "X-Llama-API-Contract-Digest": build.coreApiContract.sha256,
     "X-Llama-Agent-Client": detectAgentClient(),
     "X-Llama-Agent-Session": currentAgentSessionId(),
     "X-Llama-Command": command || "unknown",

package/lib/oauth-flow.mjs

@@ -173,6 +173,7 @@ export async function pkceLoopbackFlow({ baseUrl, scope, resource }) {
   });
 
   // Build authorize URL and open browser.
+  // @core-api-operation GET /api/oauth/authorize
   const authorizeUrl = new URL(`${baseUrl}/api/oauth/authorize`);
   authorizeUrl.searchParams.set("response_type", "code");
   authorizeUrl.searchParams.set("client_id", CLIENT_ID);

package/lib/version-check.mjs

@@ -73,6 +73,7 @@ async function fetchLatest() {
     // 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.)
+    // @core-api-ignore external npm registry version check
     const res = await fetch(REGISTRY_URL, { signal: controller.signal });
     if (!res.ok) return null;
     const data = await res.json();

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@llamaventures/cli",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "CLI + MCP server for the Llama Ventures investment workbench (command.llamaventures.vc).",
   "type": "module",
   "scripts": {
-    "test": "npm run test:agent-routing",
+    "test": "npm run test:agent-routing && npm run test:contract",
     "test:agent-routing": "node scripts/verify-agent-routing.mjs",
-    "verify:release": "npm test && node scripts/verify-tarball-clean.mjs && npm pack --dry-run"
+    "test:contract": "node --test scripts/build-manifest.test.mjs scripts/core-api-call-sites.test.mjs scripts/verify-core-api-contract.test.mjs && node scripts/verify-core-api-contract.mjs",
+    "verify:artifact": "node scripts/verify-release-artifact.mjs",
+    "verify:release": "npm test && npm run verify:artifact && node scripts/verify-tarball-clean.mjs",
+    "prepack": "node scripts/prepare-build-manifest.mjs",
+    "postpack": "node scripts/cleanup-build-manifest.mjs"
   },
   "bin": {
     "llama": "bin/llama.mjs",
@@ -14,6 +18,7 @@
   },
   "files": [
     "bin/",
+    "contracts/",
     "lib/",
     "AGENT_BRIEFING.md",
     "CHANGELOG.md",