@llamaventures/cli 2.0.0 → 2.0.2

package/AGENT_BRIEFING.md

@@ -4,6 +4,28 @@ This package is the authenticated tool boundary for Llama Command. For Deal
 work, the interface is intentionally small: search, read, create, and write.
 Do not bypass it with SQL, Google APIs, or retired HTTP routes.
 
+## Mandatory live bootstrap
+
+Before any Llama workflow, run:
+
+```bash
+llama agent bootstrap
+```
+
+The authenticated response contains the current private Llama Brain with
+exactly two components: the approved Investment Framework V3 Markdown (how to
+think) and the Llama Command operating skill (how to work). Beside Brain it
+contains the separate current Live Deal Page field contract (what every visible
+slot means and how to verify a good write). The public CLI intentionally bundles
+none of this private content; it only fetches it after authentication.
+
+CLI is the Agent's tool, not Brain. Do not substitute a private skill wrapper
+for either canonical Brain component.
+
+Do not assume the Page is only `description` plus `notes`, and do not infer its
+schema from a previous session. If bootstrap fails, repair authentication or
+upgrade the CLI before writing; do not guess the fields.
+
 ## The Deal model
 
 Each company has five business resources:
@@ -17,6 +39,21 @@ Each company has five business resources:
 Archive, trash, status, founder, opinion, fact, memo section, and artifact kind
 are data or labels inside these resources. They are not separate tools.
 
+Information and Page are deliberately different. Information is traceable
+working memory; it never becomes Page automatically. Page is the bounded,
+human-visible current projection, so patch the exact semantic fields described
+by the live contract instead of hiding structured analysis in `notes`.
+
+Every Page content field is Agent-writable. A field's `author` or
+`semanticOwner` describes attribution, not permission. Preserve a real human
+judgment with its author; otherwise label the value as an Agent proposal / 待人确认.
+
+`page.patch` uses JSON Merge Patch: objects merge, `null` deletes, and arrays
+replace the entire array. Before changing one `whatTheyDo`, `peopleSteps`,
+`foundersJson`, or `industryMaps` item, read the current Page, preserve every
+sibling item, and submit the complete updated array. The live field contract
+includes the exact payload path and write mode for all 61 semantic fields.
+
 ## Exactly four Deal actions
 
 ```bash
@@ -137,7 +174,12 @@ Update the human-facing state only when you know the intended field:
 {
   "operation": "page.patch",
   "dealId": "<uuid>",
-  "patch": {"location": "San Francisco, CA"},
+  "patch": {
+    "location": {
+      "en": "San Francisco, CA",
+      "zh": "美国加州旧金山"
+    }
+  },
   "origin": {
     "kind": "user",
     "originalUserUtterance": "The company is in SF, CA."
@@ -145,6 +187,14 @@ Update the human-facing state only when you know the intended field:
 }
 ```
 
+Human-visible Page prose is bilingual at write time. Store one field value as
+`{"en":"natural English","zh":"自然中文"}`; do not create separate English
+and Chinese Pages. Language-neutral company names, enums, URLs, numbers, dates,
+person names, and source IDs remain scalar. A localized object missing either
+language is invalid. New scalar Page prose is also invalid; historical scalar
+prose is read-compatible only. Information and raw Input retain their original
+language and provenance; do not manufacture a second source quote.
+
 Artifacts use `artifact.put`. Treat them as immutable source material. Read the
 artifact, then decide whether its content deserves Information or a Page patch.
 

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [2.0.2] - 2026-08-31
+
+- Correct the authenticated runtime model: Brain has exactly two private
+  components, Investment Framework V3 and the Llama Command operating skill.
+- Load the complete Live Deal Page field prompts beside Brain as a separate
+  current CLI/MCP tool contract.
+- Keep all Brain and Page prompt bytes server-owned and out of the public npm
+  artifact.
+
+## [2.0.1] - 2026-08-30
+
+- Ship the four-action Occam Deal surface from the audited cleanup commit.
+- Pin the CLI to the final 4.0.0 Core contract after removing the retired
+  Secretary analysis API and cron.
+- Remove legacy Deal API examples from contract-verifier fixtures so the
+  package source and publish artifact contain no retired Deal action surface.
+- Enforce bilingual values for newly Agent-authored Page prose while retaining
+  read compatibility for historical scalar content.
+- Pin the release candidate to the final local Core API 5.0 contract.
+
 ## [2.0.0] - 2026-08-30
 
 - Replace the split Deal command surface with exactly four actions: `search`,
@@ -19,6 +39,14 @@ this project adheres to [Semantic Versioning](https://semver.org).
 
 ## [Unreleased]
 
+### Changed
+- Make the authenticated live bootstrap mandatory before Deal work and clarify
+  that it loads the server-owned two-part private Brain plus the separate Live
+  Deal Page field contract. CLI remains only the tool/transport layer.
+- Teach CLI and MCP Agents that Information never updates Page automatically,
+  every Page content field is Agent-writable, and field authorship controls
+  attribution rather than permission.
+
 ## [1.26.0] - 2026-08-11
 
 ### Added

package/README.md

@@ -86,6 +86,14 @@ the initial Live Page and Information, and appends Events atomically.
 - `page.patch` — update the human-visible Live Deal Page.
 - `artifact.put` — add an immutable memo/HTML/source artifact.
 
+When Page prose is human-visible, write one bilingual field value as
+`{"en":"natural English","zh":"自然中文"}`. The Web language switch selects
+the reader's version from the same Page revision. Keep language-neutral names,
+enums, URLs, numbers, dates, and source IDs scalar. Information and raw Input
+stay in their original language with provenance. The CLI rejects new scalar
+Page prose and incomplete language pairs before they reach Core; historical
+scalar prose remains readable.
+
 Raw user input example:
 
 ```json
@@ -150,6 +158,13 @@ llama skills search "<task>"
 llama skills show <slug>
 ```
 
+Agents should run `llama agent bootstrap` before Deal work. The command loads
+the authenticated, server-owned private Brain: Investment Framework V3 for
+thinking plus the Llama Command operating skill for working. It also loads the
+separate current Live Deal Page field contract for writing. None of that private
+content is shipped in this public package; CLI is only the tool and authenticated
+transport.
+
 The live server briefing is authoritative. The bundled
 `AGENT_BRIEFING.md` is an offline fallback with the same four-action contract.
 

package/README.zh-CN.md

@@ -84,6 +84,12 @@ Core 会补上 `operation: deal.create`，创建或复用 Drive 文件夹，并
 - `page.patch`：更新人类直接看到的 Live Deal Page；
 - `artifact.put`：添加不可变的 memo、HTML 或源文件。
 
+给人看的 Page 文字必须在写入时同时提供自然的中英文：
+`{"en":"natural English","zh":"自然中文"}`。Web 的语言开关从同一个
+Page revision 选择对应内容，不创建中文页和英文页两套真相。公司名、枚举、URL、数字、日期、
+人名和 source ID 等语言无关值继续使用 scalar；Information 和原始 Input 保留原语言与 provenance。
+CLI 会在请求到达 Core 前拒绝新的 scalar Page 文案或缺少任一语言的 pair；历史 scalar 文案仍可读取。
+
 原始用户输入示例：
 
 ```json
@@ -145,6 +151,12 @@ llama skills search "<任务>"
 llama skills show <slug>
 ```
 
+Agent 在处理 Deal 前应先运行 `llama agent bootstrap`。该命令会从鉴权后的
+Llama Command 服务端加载两部分私有 Brain：负责投资思考的 Investment
+Framework V3，以及负责如何在 Command 工作的 Llama Command operating skill；
+同时加载独立的、实时的 Live Deal Page 字段契约。所有私有内容都不会进入公开
+npm 包；CLI 只是 Agent 的工具和鉴权运输层。
+
 服务端实时 briefing 是权威合同；包内 `AGENT_BRIEFING.md` 是相同四动作
 合同的离线兜底。
 

package/bin/llama-mcp.mjs

@@ -70,7 +70,7 @@ server.registerTool(
 server.registerTool(
   "read_deal",
   {
-    description: "Read one Deal. Live Page is always returned; expand only the resource needed.",
+    description: "Read one Deal. Live Page and its current private field contract are always returned; Information is memory and never updates Page automatically.",
     inputSchema: {
       dealId: z.string().min(1),
       detail: z.enum(["overview", "memory", "files", "conversation", "history", "all"]).optional(),
@@ -99,7 +99,7 @@ server.registerTool(
 server.registerTool(
   "write_deal",
   {
-    description: "The only Deal mutation tool: input.submit, information.put, page.patch, or artifact.put.",
+    description: "The only Deal mutation tool: input.submit, information.put, page.patch, or artifact.put. All Page content fields are Agent-writable; author controls attribution, not permission. Use the read/bootstrap field contract and bilingual Page prose. page.patch is JSON Merge Patch: arrays replace whole arrays, so read-modify-write and preserve sibling slots.",
     inputSchema: {
       operation: z.enum(["input.submit", "information.put", "page.patch", "artifact.put"]),
       dealId: z.string().uuid(),
@@ -152,7 +152,7 @@ server.registerTool(
 server.registerTool(
   "agent_bootstrap",
   {
-    description: "Fetch the authenticated runtime contract and visible Llama OS skills.",
+    description: "Mandatory before Llama work: fetch the authenticated two-part private Brain (Investment Framework V3 + Llama Command operating skill), the separate current Live Deal Page field contract, runtime contract, and visible Llama OS skills.",
     inputSchema: { limit: z.number().int().min(1).max(100).optional() },
   },
   async ({ limit } = {}) => {
@@ -361,7 +361,7 @@ server.registerTool(
 server.registerPrompt(
   "agent_briefing",
   {
-    description: "Fetch the authenticated current agent contract; bundled text is only an offline fallback.",
+    description: "Mandatory before Llama work: fetch the authenticated two-part private Brain, the separate current Live Deal Page field contract, and runtime contract; bundled text is only an offline fallback.",
   },
   async () => {
     const headers = await getAuthHeaders();

package/bin/llama.mjs

@@ -69,6 +69,16 @@ Exactly four actions:
   llama deal create --json <file|->
   llama deal write --json <file|->
 
+Before any Page write:
+  llama agent bootstrap
+
+The authenticated bootstrap contains the two-part private Llama Brain:
+Investment Framework V3 plus the Llama Command operating skill. It also
+contains the separate current 61-field Page contract. CLI is the tool, not
+Brain. Information never updates Page automatically. page.patch is JSON
+Merge Patch: objects merge, null deletes, and arrays replace whole arrays, so
+read-modify-write complete Page arrays and preserve sibling slots.
+
 create JSON:
   {"companyName":"Acme","page":{},"information":[],"origin":{"kind":"user","originalUserUtterance":"..."}}
 
@@ -79,21 +89,6 @@ Core owns Chat Records, append-only Deal Events, Drive provisioning, audit,
 and idempotency. User-originated work must preserve exact wording in
 origin.originalUserUtterance or reference origin.originatingChatRecordId.`;
 
-const RETIRED_DEAL_AREAS = new Set([
-  "activity",
-  "approvals",
-  "brief",
-  "claim",
-  "html",
-  "memo",
-  "mentions",
-  "nominate",
-  "nominations",
-  "post",
-  "timeline",
-  "workflow",
-]);
-
 function parseFlags(args, allowed = null) {
   const flags = {};
   const positional = [];
@@ -123,17 +118,11 @@ function usage(area) {
   console.log(area === "deal" ? HELP_DEAL : HELP_ROOT);
 }
 
-function assertActiveSurface(area, action) {
+function assertDealAction(area, action) {
   if (area === "deal" && !DEAL_ACTIONS.includes(action)) {
     throw new Error(
-      `DEAL_COMMAND_RETIRED: \`llama deal ${action || "<missing>"}\` is not part of CLI 2. ` +
-      "Use only search, read, create --json, or write --json.",
-    );
-  }
-  if (RETIRED_DEAL_AREAS.has(area)) {
-    throw new Error(
-      `DEAL_COMMAND_RETIRED: \`llama ${area}\` belonged to the split legacy Deal model. ` +
-      "Use `llama deal read` or `llama deal write --json <file|->`.",
+      `Unknown Deal action: ${action || "<missing>"}. ` +
+      "Use search, read, create --json, or write --json.",
     );
   }
 }
@@ -426,7 +415,7 @@ async function main() {
     return;
   }
 
-  assertActiveSurface(area, action);
+  assertDealAction(area, action);
 
   if (await handleAuth(area, action, rest)) return;
 

package/contracts/core-api.json

@@ -1,9 +1,9 @@
 {
   "format": "llama.core-api-contract.v1",
   "name": "llama-core-api",
-  "apiVersion": "4.0.0",
+  "apiVersion": "5.0.0",
   "openapiVersion": "3.0.3",
-  "sha256": "69b5e29ae9585915da0fa9578abfd41099545f11eba8b2d12f14aa42cc970e4e",
-  "pathCount": 247,
-  "operationCount": 323
+  "sha256": "c48ed580f9930b06445f62b94959a2ca4bf9780e59473f17588e1e6554914014",
+  "pathCount": 110,
+  "operationCount": 136
 }

package/lib/build-manifest.json

@@ -1,15 +1,15 @@
 {
   "format": "llama.cli-build.v1",
   "packageName": "@llamaventures/cli",
-  "packageVersion": "2.0.0",
-  "sourceSha": "1564eee5aa59c89fc4e245f0a5be0fcbe96d7bf9",
+  "packageVersion": "2.0.2",
+  "sourceSha": "dc52c43363b050072c70f45144909d93b4f42028",
   "sourceKind": "github",
   "sourceDirty": false,
   "coreApiContract": {
     "format": "llama.core-api-contract.v1",
     "name": "llama-core-api",
-    "apiVersion": "4.0.0",
+    "apiVersion": "5.0.0",
     "openapiVersion": "3.0.3",
-    "sha256": "69b5e29ae9585915da0fa9578abfd41099545f11eba8b2d12f14aa42cc970e4e"
+    "sha256": "c48ed580f9930b06445f62b94959a2ca4bf9780e59473f17588e1e6554914014"
   }
 }

package/lib/client.mjs

@@ -294,16 +294,6 @@ function inferCommand(method, endpoint) {
   if (pathname === "/api/occam/deals") return "deal.search";
   if (pathname === "/api/occam/deals/commands") return "deal.write";
   if (/^\/api\/occam\/deals\/[^/]+$/.test(pathname)) return "deal.read";
-  if (pathname === "/api/deals") return verb === "GET" ? "deal.search" : "deal.write";
-  if (pathname === "/api/deals/create") return "deal.create";
-  if (pathname === "/api/deals/update") return "deal.update";
-  if (/^\/api\/deals\/[^/]+\/ingest$/.test(pathname)) return "deal.ingest";
-  if (/^\/api\/deals\/[^/]+\/threads\/[^/]+$/.test(pathname)) return "deal.agent.run";
-  if (/^\/api\/deals\/[^/]+\/threads$/.test(pathname)) return "deal.thread.create";
-  if (/^\/api\/deals\/[^/]+\/facts/.test(pathname)) return verb === "GET" ? "deal.fact.list" : "deal.fact.write";
-  if (/^\/api\/deals\/[^/]+\/posts$/.test(pathname)) return "deal.post";
-  if (/^\/api\/deals\/[^/]+\/blocks/.test(pathname)) return verb === "GET" ? "brief.blocks" : "brief.write";
-  if (/^\/api\/deals\/[^/]+$/.test(pathname)) return verb === "GET" ? "deal.show" : "deal.write";
   if (pathname === "/api/me") return "auth.status";
   if (pathname.startsWith("/api/agent/skills")) return "skills.read";
   if (pathname === "/api/agent/manifest") return "agent.bootstrap";

package/lib/deal-actions.mjs

@@ -45,6 +45,89 @@ export function validateCommandOrigin(command) {
   return command;
 }
 
+function validateLocalizedTextPairs(value, path = "page") {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => validateLocalizedTextPairs(item, `${path}[${index}]`));
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  const hasEnglish = Object.prototype.hasOwnProperty.call(value, "en");
+  const hasChinese = Object.prototype.hasOwnProperty.call(value, "zh");
+  if (hasEnglish || hasChinese) {
+    if (
+      Object.keys(value).some((key) => key !== "en" && key !== "zh") ||
+      typeof value.en !== "string" ||
+      !value.en.trim() ||
+      typeof value.zh !== "string" ||
+      !value.zh.trim()
+    ) {
+      throw new Error(
+        `${path} localized text must contain only non-empty en and zh values`,
+      );
+    }
+    return;
+  }
+  for (const [key, child] of Object.entries(value)) {
+    validateLocalizedTextPairs(child, `${path}.${key}`);
+  }
+}
+
+const LANGUAGE_NEUTRAL_PAGE_KEYS = new Set([
+  "companyName", "companyKey", "state", "pipelineStatus", "stage",
+  "theirStage", "ownerUserId", "sourceUserId", "website", "dealOwner",
+  "source", "sourceDirection", "proposedAmount", "roundSize", "valuation",
+  "founders", "deckLink", "location", "foundedYear", "leadInvestor",
+  "dateAdded", "tab", "sourcePerson", "createdByName", "createdByLabel",
+  "createdVia", "id", "name", "key", "slug", "url", "href", "email",
+  "linkedin", "handle", "status", "kind", "type", "tier", "confidence",
+  "currency", "unit", "format", "mimeType", "sha256", "timestamp",
+  "date", "year",
+]);
+const LANGUAGE_NEUTRAL_PAGE_CONTAINERS = new Set([
+  "manualTags", "investors", "founderEmails", "labels", "tags",
+]);
+const OPAQUE_PAGE_CONTAINERS = new Set([
+  "migration", "extra", "fieldProvenance",
+]);
+
+function pathKeys(path) {
+  return path.match(/[^.[\]]+/g)?.filter((part) => !/^\d+$/u.test(part)) ?? [];
+}
+
+function isLanguageNeutralPagePath(path) {
+  const keys = pathKeys(path);
+  if (keys.some((key) => OPAQUE_PAGE_CONTAINERS.has(key))) return true;
+  if (keys.some((key) => LANGUAGE_NEUTRAL_PAGE_CONTAINERS.has(key))) return true;
+  const key = keys.at(-1) ?? "";
+  if (LANGUAGE_NEUTRAL_PAGE_KEYS.has(key)) return true;
+  return /(?:Id|Ids|URL|Url|URI|Uri|Link|Email|Emails|At|Date|Year|Key|Slug|Hash)$/u.test(key);
+}
+
+function validateAgentAuthoredPageProse(value, path = "page") {
+  if (typeof value === "string") {
+    if (!isLanguageNeutralPagePath(path)) {
+      throw new Error(
+        `${path} agent-authored prose must be one value with non-empty en and zh`,
+      );
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => validateAgentAuthoredPageProse(item, `${path}[${index}]`));
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  if (
+    Object.prototype.hasOwnProperty.call(value, "en") ||
+    Object.prototype.hasOwnProperty.call(value, "zh")
+  ) {
+    return;
+  }
+  for (const [key, child] of Object.entries(value)) {
+    validateAgentAuthoredPageProse(child, `${path}.${key}`);
+  }
+}
+
 export async function readJsonInput(path, stdin = process.stdin) {
   if (!path || path === true) throw new Error("--json <file|-> is required");
   const text = path === "-"
@@ -98,5 +181,13 @@ export function prepareDealCommand(action, input) {
   if (action === "write" && !DEAL_WRITE_OPERATIONS.includes(command.operation)) {
     throw new Error(`write JSON operation must be ${DEAL_WRITE_OPERATIONS.join(", ")}`);
   }
+  if (action === "create") {
+    validateLocalizedTextPairs(command.page ?? {});
+    validateAgentAuthoredPageProse(command.page ?? {});
+  }
+  if (action === "write" && command.operation === "page.patch") {
+    validateLocalizedTextPairs(command.patch ?? {});
+    validateAgentAuthoredPageProse(command.patch ?? {});
+  }
   return ensureIdempotencyKey(validateCommandOrigin(command));
 }

package/package.json

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